{"id":26450998,"url":"https://github.com/syniverse/messaging-python","last_synced_at":"2025-07-05T23:09:16.157Z","repository":{"id":89165154,"uuid":"71072760","full_name":"Syniverse/Messaging-Python","owner":"Syniverse","description":"Python SDK for SCG Messaging APIs","archived":false,"fork":false,"pushed_at":"2018-10-08T15:46:53.000Z","size":39,"stargazers_count":2,"open_issues_count":0,"forks_count":2,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-07-05T23:09:14.656Z","etag":null,"topics":["mms","push-notifications","python-sdk","scg-api","senderid","sms-api","voice"],"latest_commit_sha":null,"homepage":"https://developer.syniverse.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Syniverse.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-10-16T19:38:00.000Z","updated_at":"2020-09-08T19:15:03.000Z","dependencies_parsed_at":"2023-06-14T06:15:21.813Z","dependency_job_id":null,"html_url":"https://github.com/Syniverse/Messaging-Python","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Syniverse/Messaging-Python","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Syniverse%2FMessaging-Python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Syniverse%2FMessaging-Python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Syniverse%2FMessaging-Python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Syniverse%2FMessaging-Python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Syniverse","download_url":"https://codeload.github.com/Syniverse/Messaging-Python/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Syniverse%2FMessaging-Python/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263819235,"owners_count":23516122,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mms","push-notifications","python-sdk","scg-api","senderid","sms-api","voice"],"created_at":"2025-03-18T16:07:06.095Z","updated_at":"2025-07-05T23:09:16.140Z","avatar_url":"https://github.com/Syniverse.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Python SDK for SCG Messaging APIs\n\nThis is the Python version of the SCG API.\nWe have prepared simple to use Python classes, representing the\ndifferent REST API interfaces.\n\nThe Python API hides some of the REST API's constraints, like\nlists being returned in logical pages of \u003ci\u003en\u003c/i\u003e records. With the\npython SDK, the list() method returns a generator that returns\nsingle list items, until there are no more.\n\nThe SDK is compatible with Python 2.7 and 3.5\n\nPlease register for a free account at https://developer.syniverse.com to get your API keys.\n\n## How to use the SDK\nAll the data objects follow a common pattern.\n\nYou get a handle to a resource (like Contact or SenderId) by getting\nan instance of scgapi.Object.Resource(session).\n\nThe session object is obtained from Scg.connect(), and gives you\nsequential (blocking) access to the REST API. If you want to\nprocess many requests in parallel, you need many session objects.\nPython has some architectural constrains on true multiprocessing,\nbut as REST requests typically waits on the server for quite some\ntime (measured in milliseconds or even seconds), you can achieve\nquite some extra performance from using a large number of sessions.\n\nThe resource object you get from  scgapi.\u003cObject\u003e.Resource(session)\ntypically has \u003cb\u003elist()\u003c/b\u003e and \u003cb\u003ecreate()\u003c/b\u003e methods (depending\non the actual REST API methods available for that data type).\n\nTo list the data objects for a resource, like your Contacts,\nyou can call list() without any arguments to get all the contacts,\nor list(key=value[, key=value]...) to filter the result-set. list()\nreturns a generator that let's you iterate over the data-set.\n\nYou can create an object by calling create() with name=value pairs,\nor by constructing and initializing a data object, and then passing\nit to create().\n\n```python\n# Create from name/value pairs\nres = scgapi.Contact.Resource(session)\nid = create(first_name=\"John\", last_name=\"Doe\")\n```\n\n```python\n# Create from object\nres = scgapi.Contact.Resource(session)\ncontact = scgapi.Contact()\ncontact.first_name=\"John\"\ncontact.last_name=\"Doe\"\nid = create(contact)\n```\n\nAll objects that can be updated or deleted has \u003cb\u003eupdate()\u003c/b\u003e and/or\n\u003cb\u003edelete()\u003c/b\u003e methods. The resource of an object also have \u003cb\u003edelete()\u003c/b\u003e\nmethods, so if you need to delete an object you just know by it's id,\nthere is no need to instantiate it. You just call\n ```python\nres.delete(id)\n```\n\nSome objects has methods that let you add/query or delete\nother objects or references it holds to other objects. For\nexample, when you create a message-request to a group of\ncontacts, you may generate a large number of message objects.\nThese can be iterated over from scgapi.MessageRequest.list_messages()\n\n```python\nres = mrq_res = scgapi.MessageRequest.Resource(session)\nrequest = mrq_res.get(\"qteDxVrAhlMlmTwDrMAvN3\")\nfor msg in request.list_messages():\n    # Do something...\n```\n\n## Error handling\nErrors are reported through exceptions.\n\n## Special considerations\nThe REST API has some read-only\nproperties for some objects (like the server-generated id). These\nare retained as read-only in this SDK. In the source code, the\nread-only properties are hidden with a prefix underscore and\naccessed trough Python reader properties. So even if the 'id' of\nall objects are read-only, you can still get the value by accessing\n'instance.id'. The same applies for other read-only properties.\n\nPython have some reserved words that cannot be used as an argument name.\nIn this SDK, we have solved this by allowing a padding underscore\non all argument names that represents an object property.\n\nFor example, if we want to create an object that has a property name \nof 'from', and set that property value, we can write:\n```python\nres.create(foo=\"Foo\", from_=\"Me\")\n```\nThe same applies for filters in the list() methods.\n```python\nres.list(foo=\"Foo\", from_=\"Me\")\n```\n\n# Some examples\n\n## Listing Sender Ids\nIf you want to list available Sender Ids, it can be done as easy as:\n```python\ndef list_senderids(api, config):\n    # Construct an instance of the authentication object\n    # with authentication data from a json file (auth.json)\n    auth = scgapi.AuthInfo(config=config)\n\n    # Prepare a session to the server.\n    scg = Scg()\n\n    # Prepare a session to the server.\n    session = scg.connect(api, auth)\n\n    # Request the complete list of sender id's from the server,\n    # where the class_id is COMMECRIAL and state is ACTIVE, and iterate\n    # over them one by one.\n    res = scgapi.SenderId.Resource(session)\n    for sid in res.list(class_id=\"COMMERCIAL\", state=\"ACTIVE\"):\n        print('Sender id {} has capabilities {}'.format(sid.address,\n                                                        sid.capabilities))\n```\n[Full example](examples/list_senderids.py)\n\nThis should produce output like:\n```text\nSender id +15552223561 has capabilities ['VOICE']\nSender id +15552460009 has capabilities ['VOICE']\nSender id 15555551122 has capabilities ['SMS']\nSender id 155528999 has capabilities ['MMS', 'SMS']\n```\n\n\n## Adding and updating a Contact\n```python\ndef create_and_update_contact(api, config, mdn):\n    # Construct an instance of the authentication object\n    # with authentication data from a json file (auth.json)\n    auth = scgapi.AuthInfo(config=config)\n\n    # Prepare a session to the server.\n    scg = Scg()\n\n    # Prepare a session to the server.\n    session = scg.connect(api, auth)\n\n    res = res = scgapi.Contact.Resource(session)\n\n    # Create a contact. Note that we get a contact id (string), not a Contact\n    # instance from Create.\n    contact_id = res.create(\n        first_name=\"John\",\n        last_name=\"Doe\",\n        primary_mdn=mdn)\n\n    contact = res.get(contact_id)\n    contact.last_name = 'Anderson'\n    contact.update()\n\n    # Make sure we have same data as the server does\n    updated_contact = res.get(contact_id)\n\n    print(\"John Doe changed name to {} {}\".format(updated_contact.first_name,\n                                                  updated_contact.last_name))\n\n    # Delete the contact on the server.\n    contact.delete()\n```\n[Full example](examples/update_contact.py)\n\nThis should produce output similar to:\n```text\nJohn Doe changed name to John Anderson\n```\n\n## Sending a SMS to a Mobile number\n```python\ndef send_sms(api, config, mdn, senderid):\n    # Construct an instance of the authentication object\n    # with authentication data from a json file (auth.json)\n    auth = scgapi.AuthInfo(config=config)\n\n    # Prepare a session to the server.\n    scg = Scg()\n\n    # Prepare a session to the server.\n    session = scg.connect(api, auth)\n\n    # Get a MessageRequest resource\n    res = scgapi.MessageRequest.Resource(session)\n\n    # Send the message\n    # Note that from_ has a padding underscore due to\n    # syntax constraints in Python.\n    reqid = res.create(\n        from_=senderid,\n        to=[mdn],\n        body=\"Hello, this is a SMS message.\")\n\n    print('Sent message request {}'.format(reqid))\n\n```\n[Full example](examples/send_sms.py)\n\nThis should produce output similar to:\n```text\nSent message request aQWY9PeMCO01TEH9bk1ek5\n```\n\n## Sending a Message to a Contact\n\nThis works as above, except for the to field in create()\n```python\ncontact_id = \"\u003cId of an existing contact\u003e\"\nreqid = mrq_res.create(\n    from_=sender_id,\n    to=[\"contact:\" + contact_id],\n    body=\"Hello, this is a SMS message.\")\n```\n\n## Sending a Message to a Contact Group\n```python\ndef send_sms(api, config, bob_mdn, alice_mdn, senderid):\n\n    # Construct an instance of the authentication object\n    # with authentication data from a json file (auth.json)\n    auth = scgapi.AuthInfo(config=config)\n\n    # Prepare a session to the server.\n    scg = Scg()\n\n    # Prepare a session to the server.\n    session = scg.connect(api, auth)\n\n    # Create some contacts\n    contacts_res = scgapi.Contact.Resource(session)\n    bob = contacts_res.create(first_name=\"Bob\", primary_mdn=bob_mdn)\n    alice = contacts_res.create(first_name=\"Alice\", primary_mdn=alice_mdn)\n\n    # Create a group\n    grp_res = scgapi.ContactGroup.Resource(session)\n    friends = grp_res.get(grp_res.create(name=\"Our Friends\"))\n\n    # add our new friends to the group\n    friends.add_contact([bob, alice])\n\n    # Get a MessageRequest resource\n    mrq_res = scgapi.MessageRequest.Resource(session)\n\n    # Send the message\n    # Note that from_ has a padding underscore due to\n    # syntax constraints in Python.\n    reqid = mrq_res.create(\n        from_=senderid,\n        to=[\"group:\" + friends.id],\n        body=\"Hello, this is a SMS message to our friends.\")\n\n    print('Sent message request {} to group {}'.format(reqid, friends.id))\n```\n[Full example](examples/send_sms_to_grp.py)\n\n\n## Sending a MMS with an attachment\n\n```python\ndef upload_attachment(session, path):\n    res = scgapi.Attachment.Resource(session)\n    att = res.create_and_upload(path, type=\"image/jpeg\",\n        name=\"attachment\", filename=\"attachment.jpg\")\n    print('Uploaded attachment {}'.format(att.id))\n    return att\n\ndef send_mms(api, config, mdn, senderid, attachment):\n    # Construct an instance of the authentication object\n    # with authentication data from a json file (auth.json)\n    auth = scgapi.AuthInfo(config=config)\n\n    # Prepare a session to the server.\n    scg = Scg()\n\n    # Prepare a session to the server.\n    session = scg.connect(api, auth)\n\n    # Get a MessageRequest resource\n    res = scgapi.MessageRequest.Resource(session)\n\n    # Upload the attachment to the server.\n    # Returns an instance of scgapi.Attachment\n    att = upload_attachment(session, attachment)\n\n    # Send the message\n    # Note that from_ has a padding underscore due to\n    # syntax constraints in Python.\n    reqid = res.create(\n        from_=senderid,\n        to=[mdn],\n        attachments=[att.id],\n        body=\"Hello, this is a MMS message.\")\n\n    print('Sent message request {}'.format(reqid))\n```\n```text\nUploaded attachment wMjURamVl9ITSXRJSkMoR4\nSent message request 9NeqCbNXBYvRO73jC2rbc5\n```\n[Full example](examples/send_mms.py)\n\n\n## Checking the state of a Message Request\n```python\ndef check_state(api, config, mrq):\n\n    # Construct an instance of the authentication object\n    # with authentication data from a json file (auth.json)\n    auth = scgapi.AuthInfo(config=config)\n\n    # Prepare a session to the server.\n    scg = Scg()\n\n    # Prepare a session to the server.\n    session = scg.connect(auth, api)\n\n    # Get a MessageRequest resource\n    res = scgapi.MessageRequest.Resource(session)\n\n    # Get the message request instance\n    message_request = res.get(mrq)\n\n    print('Message Request {} is in state {} with {} delivered and {} failed messages'.format(\n        message_request.id,\n        message_request.state,\n        message_request.delivered_count,\n        message_request.failed_count))\n\n    # Get a generator to the messages generated by this message request\n    msgs = message_request.list_messages()\n\n    # Print each message.\n    #\n    # Since the SDK use a generator and not a list, we will only have a small\n    # number of messages in memory at any time, allowing us to iterate\n    # over many messages if required, even on machines with very\n    # limited internal memory.\n    for msg in msgs:\n        print(' - Message {} is in state {}, error code: {}, error reason: {}'.format(\n            msg.id, msg.state, msg.failure_code, msg.failure_details))\n        for frag in msg.fragments_info:\n            print ('   - Fragment {} has state {}'.format(frag.fragment_id, frag.fragment_state))\n```\n[Full example](examples/check_message_request_state.py)\n\nThis should produce output similar to:\n```text\nMessage Request mjwLKqumB82wGAU8kwv317 is in state COMPLETED with 0 delivered and 0 failed messages\n - Message TXgPr187zLzUAWYEorHmU2 is in state SENT, error code: None, error reason: None\n   - Fragment A87UrgwRiK0QnjDM3AMEv2 has state SENT\n\n```\n\n# Using with virtualenv\n\nIn order to use the library in a private environment,\nwithout creating conflicts with other Python packages,\nyou can use virtualenv. The example below is tested with\nUbuntu zesty.\n\n```bash\n$ virtualenv -p /usr/bin/python3 env-p3\n$ . ./env-p3/bin/activate\n$ pip install -r requirements.txt\n$ python examples/list_senderids.py \n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsyniverse%2Fmessaging-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsyniverse%2Fmessaging-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsyniverse%2Fmessaging-python/lists"}