my-bpost-api 0.2.1
Unofficial wrapper for the API used by the My Bpost app
License: MIT
Requires Python: >=3.8,<4.0
Keywords: bpost,mail,api

# my-bpost-api

[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/sdebruyn/my-bpost-api/main.svg)](https://results.pre-commit.ci/latest/github/sdebruyn/my-bpost-api/main)
![GitHub](https://img.shields.io/github/license/sdebruyn/my-bpost-api)
![PyPI](https://img.shields.io/pypi/v/my-bpost-api)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/my-bpost-api)
![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)

Unofficial wrapper for the API used by the My Bpost app.
This is used by the [Home Assistant integration](https://github.com/sdebruyn/homeassistant-bpost-integration).

## Features

* [x] Authenticate with your My Bpost account
* [x] Fetch your mail configured in _My mail_ in the mobile app
* [ ] Start tracking a new parcel (does not seem to properly sync across different sessions)
* [x] Fetch the status of your parcels (does not seem to properly sync to your account)
* [ ] Refresh your access token (seems broken in the API)

## Documentation

The code is pretty self-explanatory, take a look at the example below:

```python
bpost_api = BpostApi(email="your@email.be")

await bpost_api.async_users_email_login() # this will send you an email with a verification code
await bpost_api.async_users_email_login_verify_code(code="123456") # use the code from the email you've received (valid for 24hrs)

# now your access and refresh (unused) token are stored inside the object
# if you want to reuse them later, just create a new instance and add the tokens:
access_token = bpost_api.token
refresh_token = bpost_api.refresh_token
bpost_authenticated_api = BpostApi(email="your@email.be", token=access_token, refresh_token=refresh_token)
# the access token is a regular JWT token, so you can inspect to see when it expires

mail = await bpost_api.async_fetch_mail()
# this will only work if you've properly configured this service in the mobile app

did_user_configure_my_mail_service = mail["isMMTSubscribed"]
amount_of_mails_receiving_today = len(mail["Active"])
was_mail_processed_today = not mail["isHoliday"] and not mail["isMailProcessed"]

# the response contains a list of mail in the key "Active" for mails you still have to receive
# and "History" for previously scanned mail

example_mail = mail["Active"][0]
unique_id_of_this_mail = example_mail["tagId"]
expected_delivery_of_this_mail = example_mail["expectedDeliveryDate"]
image_url_as_scanned_in_sorting_center = example_mail["mailURL"]
image_bytes = await bpost_api.async_get_mail_image(image_url_as_scanned_in_sorting_center)
```

Exceptions:
* `BpostApiException`: thrown when the API returns an error
* `AuthenticationException`: thrown when an error occurs during authentication
* `aiohttp.ClientError`: error during HTTPS communication

Other options:

* `api_key`: use a custom API key instead of the default one (taken from Android app)
* `language`: `en` by default, changes the language of API responses
* `session_callback`: provide a callable that returns an [aiohttp](https://docs.aiohttp.org/) session if you want more control over the session

## License

MIT license

## Contributing

1. Install [poetry](https://python-poetry.org/)
2. Clone the repository
3. Install dependencies `poetry install`
4. Activate venv: `poetry shell`
5. Configure pre-commit: `pre-commit install`
6. Configure your IDE to use the poetry venv (`poetry env info`)