bestsms 2.4.0.2
BestSMS REST API Helper Library for Python
License: MIT
Keywords: bestsms, api, sms

# bestsms

## Documentation

The documentation for the BestSMS API can be found [here][apidocs].

## Versions

`bestsms` uses a modified version of [Semantic Versioning](https://semver.org) for all changes. [See this document](VERSIONS.md) for details.

### Supported Python Versions

This library supports the following Python implementations:

* Python 3.9
* Python 3.10
* Python 3.11
* Python 3.12

## Installation

Install from PyPi using [pip](http://www.pip-installer.org/en/latest/), a
package manager for Python.

    pip install bestsms

Don't have pip installed? Try installing it, by running this from the command
line:

    $ curl https://raw.github.com/pypa/pip/master/contrib/get-pip.py | python

    python setup.py install

You may need to run the above commands with `sudo`.

## Getting Started

Getting started with the BestSMS API couldn't be easier. Create a
`Client` and you're ready to go.

### API Credentials

The `BestSMS` needs your BestSMS API credentials (BestSMS Auth Tokens). You can either pass these
directly to the constructor (see the code below) or via environment variables.

```python
from bestsms import BestSMS

client = BestSMS(
    AuthToken = "[Your Auth Token]"
)
```

### Send Message

Send SMS through `bestsms` library.

#### Send SMS

```python
from bestsms import BestSMS

client = BestSMS(
    AuthToken="[Your Auth Token]"
)

response = client.Messaging.SMS.SendMessage(
    Reference="Test",
    MessageText = "Test SMS Message click [[Reply]] to opt out",
    Recipients = ["+61421123123"],
)

print(response)
```

### Reports

Retrieve your message status using `bestsms` library.

#### Reports - Get Message Status

```python
from bestsms import BestSMS

client = BestSMS(
    AuthToken="[Your Auth Token]"
)

response = client.Reports.Status.Poll(
    MessageID="ID123456"
)

print(response)
```

#### Reports - Get SMS Reply

```python
from bestsms import BestSMS

client = BestSMS(
    AuthToken="[Your Auth Token]"
)

request = client.Reports.SMSReply.Poll(
    MessageID="ID123456"
)

print(response)
```

#### Reports - Get SMS Received List

```python
from bestsms import BestSMS

client = BestSMS(
    AuthToken="[Your Auth Token]"
)

response = client.Reports.SMSReceived.Poll(
    #TimePeriod = 1440
    DateFrom="2023-07-01 00:00:00",
    DateTo="2023-08-01 00:00:00"
)

print(response)
```

### Actions

Amend your message using `bestsms` library.

#### Actions - Abort Pending/Delayed Job

```python
from bestsms import BestSMS

client = BestSMS(
    AuthToken="[Your Auth Token]"
)

response = client.Actions.Abort.SendRequest(
    MessageID="ID123456"
)

print(response)
```

#### Actions - Resubmit Failed Job

```python
from bestsms import BestSMS

client = BestSMS(
    AuthToken="[Your Auth Token]"
)

response = client.Actions.Resubmit.SendRequest(
    MessageID="ID123456",
    SendTime="2023-07-10T09:00"    #optional
)

print(response)
```

#### Actions - Reschedule DELAYED Job

```python
from bestsms import BestSMS

client = BestSMS(
    AuthToken="[Your Auth Token]"
)

response = client.Actions.Reschedule.SendRequest(
    MessageID="ID123456",
    SendTime=datetime.now()
)

print(response)
```

### Addressbook - Contacts

Manage your contacts using `bestsms` library.

#### Contacts - List

```python
from bestsms import BestSMS

client = BestSMS(
    AuthToken="[Your Auth Token]"
)

response = client.Addressbook.Contact.List(
    RecordsPerPage=10,
    Page=1
)

print(response)
```

#### Contacts - Detail

```python
from bestsms import BestSMS

client = BestSMS(
    AuthToken="[Your Auth Token]"
)

response = client.Addressbook.Contact.Detail(
    ContactID="[Contact ID]"
)

print(response)
```

#### Contacts - Create

```python
from bestsms import BestSMS

client = BestSMS(
    AuthToken="[Your Auth Token]"
)

response = client.Addressbook.Contact.Create(
    Title="Mr",
    Company="BestSMS",
    FirstName="First",
    LastName="Last",
    MobilePhone="+61421222233",
    ViewPublic="Account",
    EditPublid="Account"
)

print(response)
```

#### Contacts - Update

```python
from bestsms import BestSMS

client = BestSMS(
    AuthToken="[Your Auth Token]"
)

response = client.Addressbook.Contact.Update(
    ContactID="[Contact ID]",
    Attention="Test Attention"
)

print(response)
```

#### Contacts - Delete

```python
from bestsms import BestSMS

client = BestSMS(
    AuthToken="[Your Auth Token]"
)

response = client.Addressbook.Contact.Delete(
    ContactID="[Contact ID]"
)

print(response)
```

### Addressbook - Contact Group

Manage your contact group relationship using `bestsms` library.

#### Contact Group - List

```python
from bestsms import BestSMS

client = BestSMS(
    AuthToken="[Your Auth Token]"
)

response = client.Addressbook.ContactGroup.List(
    RecordsPerPage=10,
    Page=1,
    ContactID="[Contact ID]"
)

print(response)
```

#### Contact Group - Detail

```python
from bestsms import BestSMS

client = BestSMS(
    AuthToken="[Your Auth Token]"
)

response = client.Addressbook.ContactGroup.Detail(
    ContactID="[Contact ID]",
    GroupCode="[Group Code]"
)

print(response)
```

#### Contact Group - Create

```python
from bestsms import BestSMS

client = BestSMS(
    AuthToken="[Your Auth Token]"
)

response = client.Addressbook.ContactGroup.Create(
    ContactID="[Contact ID]",
    GroupCode="[Group Code]"
)

print(response)
```

#### Contact Group - Delete

```python
from bestsms import BestSMS

client = BestSMS(
    AuthToken="[Your Auth Token]"
)

response = client.Addressbook.ContactGroup.Delete(
    ContactID="[Contact ID]",
    GroupCode="[Group Code]"
)

print(response)
```

### Addressbook - Group

Manage your group using `bestsms` library.

#### Group - List

```python
from bestsms import BestSMS

client = BestSMS(
    AuthToken="[Your Auth Token]"
)

response = client.Addressbook.Group.List(
    RecordsPerPage=10,
    Page=1
)

print(response)
```

#### Group - Detail

```python
from bestsms import BestSMS

client = BestSMS(
    AuthToken="[Your Auth Token]"
)

response = client.Addressbook.Group.Detail(
    GroupCode="[Group Code]"
)

print(response)
```

#### Group - Create

```python
from bestsms import BestSMS

client = BestSMS(
    AuthToken="[Your Auth Token]"
)

response = client.Addressbook.Group.Create(
    GroupCode="[Group Code]",
    GroupName="[Group Name]"
)

print(response)
```

#### Group - Update

```python
from bestsms import BestSMS

client = BestSMS(
    AuthToken="[Your Auth Token]"
)

response = client.Addressbook.Group.Update(
    GroupCode="[Group Code]",
    GroupName="[Group Name]"
)

print(response)
```

#### Group - Delete

```python
from bestsms import BestSMS

client = BestSMS(
    AuthToken="[Your Auth Token]"
)

response = client.Addressbook.Group.Delete(
    GroupCode="[Group Code]"
)

print(response)
```

### Addressbook - Group Contact

Manage your group contact relationship using `bestsms` library.

#### Group Contact - List

```python
from bestsms import BestSMS

client = BestSMS(
    AuthToken="[Your Auth Token]"
)

response = client.Addressbook.GroupContact.List(
    RecordsPerPage=10,
    Page=1,
    GroupCode="[Group Code]"
)

print(response)
```

#### Group Contact - Detail

```python
from bestsms import BestSMS

client = BestSMS(
    AuthToken="[Your Auth Token]"
)

response = client.Addressbook.GroupContact.Detail(
    GroupCode="[Group Code]",
    ContactID="[Contact ID]"
)

print(response)
```

#### Group Contact - Create

```python
from bestsms import BestSMS

client = BestSMS(
    AuthToken="[Your Auth Token]"
)

response = client.Addressbook.GroupContact.Create(
    GroupCode="[Group Code]",
    ContactID="[Contact ID]"
)

print(response)
```

#### Group Contact - Delete

```python
from bestsms import BestSMS

client = BestSMS(
    AuthToken="[Your Auth Token]"
)

response = client.Addressbook.GroupContact.Delete(
    GroupCode="[Group Code]",
    ContactID="[Contact ID]"
)

print(response)
```

### Getting help

If you need help installing or using the library, please check the [BestSMS Contact](https://bestsms.au/contact) if you don't find an answer to your question.

[apidocs]: https://bestsms.au/Docs/PythonLib/