Skip to main content

An API for the Threema gateway service to send and receive messages including text, images, files and delivery reports.

Project description

Travis codecov

threema-gateway is a Python 3 module for the Threema gateway service. This API can be used to send and receive text messages to and from any Threema user.


On machines where Python 3 is not the default Python runtime, you should use pip3 instead of pip.


$ sudo apt-get install python3 python3-pip

We recommend using venv to create an isolated Python environment:

$ pyvenv venv

You can switch into the created virtual environment venv by running this command:

$ source venv/bin/activate

While the virtual environment is active, all packages installed using pip will be installed into this environment.

To deactivate the virtual environment, just run:

$ deactivate

If you want easier handling of your virtualenvs, you might also want to take a look at virtualenvwrapper.


If you are using a virtual environment, activate it first.

Install the module by running:

$ pip install threema.gateway

The dependency libnacl will be installed automatically. However, you may need to install libsodium for libnacl to work.

Command Line Usage

The script threema-gateway provides a command line interface for the Threema gateway. Run the following command to see usage information:

$ threema-gateway --help


You can find a few example scripts in the examples/ directory.

Note that most of them need to be adjusted to at least add your gateway ID credentials before they run successfully.

Feature Levels




















You can see the implemented feature level by invoking the following command:

$ threema-gateway version


If you want to contribute to this project, you should install the optional dev requirements of the project in an editable environment:

$ git clone
$ cd threema-msgapi-sdk-python
$ pip install -e .[dev]

Before creating a pull request, it is recommended to run the following commands to check for code style violations (flake8), optimise imports (isort) and run the project’s tests:

$ flake8 .
$ isort .
$ py.test

You should also run the type checker that might catch some additional bugs:

$ mypy tests examples threema

Reporting Security Issues

Please report security issues directly to one or both of the following contacts:


6.0.0 (2022-06-13)


  • Add support for Python 3.10

  • Drop support for Python versions below 3.7

  • Major dependencies bump to increase compatibility with other packages

  • Updated all tests to work with the newest dependencies

  • Changed CLI syntax: All commands are now dash-case instead of snake_case, e.g. the send_e2e command is now called send-e2e.

5.0.0 (2021-05-17)

  • Add custom session and session arguments to Connection (#55, #56)

  • Remove the fingerprint and verify_fingerprint arguments, see #55 for a detailed explanation and how to achieve pinning

4.0.0 (2021-01-23)


  • Drop support for Python versions below 3.6.1.

  • Remove ReceiptType.user_ack after deprecation. Use ReceiptType.user_acknowledge instead.

  • Simplify util.aio_run. It does not allow for passing a specific event loop or closing the event loop on completion any longer.

  • Rename util.aio_run_proxy_decorator to aio_run_proxy. It now always creates the class instance within a running event loop.


  • In async mode, creation of the Connection instance must now be done within an async function.

  • If you have used a with context manager block in async mode before, you must now do this within an async with asynchronous context manager. No change is required in blocking mode.

  • Connection.close is now an async function.


  • The callback server has been refactored and the AbstractCallback class has been removed for more flexibility and control of the underlying aiohttp server. Take a look at examples/ on how to use it.

  • The callback server CLI has been removed because it was redundant. The example provides the same functionality.

3.1.0 (2020-04-21)

  • Add video message

  • Fix slightly off calculation of image byte length

3.0.6 (2017-09-22)

  • Migrate to aiohttp2

3.0.5 (2017-07-25)

  • Fix to handle new libnacl exceptions.

3.0.4 (2017-05-23)

  • Fix CLI

3.0.2 (2017-05-12)

  • Initial publication on PyPI

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

threema.gateway-6.0.0.tar.gz (437.8 kB view hashes)

Uploaded source

Built Distribution

threema.gateway-6.0.0-py37.py38.py39.py310-none-any.whl (31.4 kB view hashes)

Uploaded py37 py38 py39 py310

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page