Metadata-Version: 2.1
Name: fred-messenger
Version: 0.6.1
Summary: Fred-messenger is a service for sending and archiving various types of messages.
Author: Vlastimil Zíma
Author-email: vlastimil.zima@nic.cz
License: GPLv3+
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: No Input/Output (Daemon)
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications
Classifier: Topic :: Communications :: Email
Classifier: Topic :: Internet
Classifier: Topic :: Office/Business
Classifier: Typing :: Typed
Requires-Python: ~=3.8
Provides-Extra: quality
Provides-Extra: reflection
Provides-Extra: sentry
Provides-Extra: test
Provides-Extra: types

==============
Fred-messenger
==============

Fred-messenger is a service for sending and archiving various types of messages.

Learn more about the project and our community on the `FRED's home page`__

.. _FRED: https://fred.nic.cz

__ FRED_

Configuration
=============

Messenger searches for configuration files in following order:

1. Configuration file set by ``MESSENGER_CONFIG`` environment variable.
2. Configuration file set by ``--config`` option of a command.
3. ``~/.fred/messenger.conf``
4. ``/etc/fred/messenger.conf``

The configuration file is in YAML format with following options:

``clean_days``
--------------
Lifetime of an message that is not to be archived in days.
Applies to messages with ``archive`` flag disabled or error messages.
Default is 30 days.

``db_connection``
-----------------
A connection string to database.
See https://docs.sqlalchemy.org/core/engines.html#database-urls for possible values.
Default is ``sqlite:///:memory:``.

``db_echo``
-----------
Whether to log SQL statements.
Default is ``False``.

``delivery_backend``
--------------------
Dotted path to a backend used for processing e-mail message delivery.
Default is ``messenger.delivery.email.ImapDelivery``.

``delivery_options``
--------------------
Dictionary with options for the delivery backend.
Default is empty.

``fileman_netloc``
------------------
Network location, i.e. host and port, of a fileman service.
Default is ``None``, i.e. fileman disabled.
Emails with attachments will not be send.

``fred_db_connection``
----------------------
A connection string to FRED database for mail archive migration.
See https://docs.sqlalchemy.org/core/engines.html#database-urls for possible values.
Default is ``None``, which causes error when running migration.

``logging``
-----------
Logging configuration, see https://docs.python.org/3.8/library/logging.config.html for possible values.
Default is ``None``, i.e. use ``logging`` defaults.

``grpc_max_workers``
--------------------
The maximum number of workers for gRPC server, see https://docs.python.org/3/library/concurrent.futures.html#concurrent.futures.ThreadPoolExecutor.
Default is ``None``, i.e. use Python library default.

``grpc_maximum_concurrent_rpcs``
--------------------------------
The maximum number of concurrent RPCs this server will service, see http://grpc.github.io/grpc/python/grpc.html#grpc.server.
Default is ``None``, i.e. no limit.

``grpc_options``
----------------
Custom options for a gRPC server.
Valid value is a list of key-value pairs.
Default is ``None``, i.e. use gRPC defaults.

``grpc_port``
-------------
Port to which the messenger gRPC service will bind and listen.
Default is 50051.

``monitoring_email``
--------------------
An email address which is excluded from migrations of emails in ``migrate_archive`` command.
Default is ``None``, i.e. migrate all emails.

``msgid_domain``
----------------
Domain portion of generated Message-ID.
Default is ``None``, i.e. the local hostname.

``processors``
--------------
Default is empty.

Definition of message processors in a complex structure.
The setting maps transport method to a list of processor settings.
Each processor setting has to define ``class`` with dotted path to a processor class used and optionally keyword arguments for the processor.
Example::

    processors:
        email:
            - class: messenger.processors.VcardEmailProcessor
              data: "VCARD_DATA"

By default, no processors are defined.

``senders``
-----------
Definition of message senders in a complex structure.
The highest level maps transport method to senders.
Medium level maps sender alias to its settings.
Inner level contains a backend settings:

* ``backend`` contains dotted path to a backend. This setting is required.
* ``filters`` contain a filter settings, see below.
* ``options`` contains mapping of backend specific options.

Example::

    senders:
        smtp:
            backend: messenger.backends.email.SmtpBackend
            options:
                host: red-dwarf.example.org
                default_from: holly@example.org

By default, no senders are defined.

``filters``
^^^^^^^^^^^
A setting of filters as a list of filter settings.
Each filter setting has to define ``class`` with dotted path to a filter class used and optionally keyword arguments for the filter.
Example::

    filters:
        - class: red.dwarf.IgnoreFilter
          ignore: Rimmer

By default, no filters are defined.

``sentry``
----------
Sentry settings in a nested structure.
May contain following keys:

 * ``dsn`` contains data source name (DSN), see https://docs.sentry.io/product/sentry-basics/dsn-explainer/.
   If not provided, Sentry client is not set up.
 * ``environment`` may contain an environment identifier.
 * ``ca_certs`` may contain a path to CA certificates file.

``test_db_connection``
----------------------
A connection string to database to be used in tests.
See https://docs.sqlalchemy.org/core/engines.html#database-urls for possible values.
Default is ``sqlite:///:memory:``.

ChangeLog
=========

.. contents:: Releases
   :backlinks: none
   :local:

0.6.1 (2025-07-01)
------------------

* Handle empty context correctly (#124).

0.6.0 (2025-06-10)
------------------

* Add ``LockFileFilter`` (#108).
* Add ``--control-file`` to ``sender`` (#117).
* Fix annotations.
* Fix for click 8.2 and 8.2.1

0.5.5 (2023-11-16)
------------------

* Add support for python 3.11 and 3.12.
* Drop support for python 3.7.
* Use ``imap_tools`` 1.X (#89).
* Use ``fred-filed`` 0.3.
* Fix typing.
* Fix ``StrEnum`` and use backport.

0.5.4 (2023-02-08)
------------------

* Fix emails with multiple recipients (#87).
* Fix signatures on multipart alternative emails (#88).
* Fix bugs in ``send-message`` script.

0.5.3 (2023-01-26)
------------------

* Prevent sending one message multiple times (#84).
* Fix email ``To`` header (#85).
* Fix typing and flake8.

0.5.2 (2022-07-25)
------------------

* Always convert DSN values to string (#79).

0.5.1 (2022-06-28)
------------------

* Optimize email search in delivery (#76).

0.5.0 (2022-06-20)
------------------

* Replace EasySettings with pydantic (#33).
* Use API 1.3 (#70).
* Add a ``folder`` option to email delivery (#57).
* Fix delivery for rfc822 MIME type (#60).
* Skip autosubmitted emails in delivery processing (#62).
* Add an option to skip delivered emails (#63).
* Improve delivery processing (#42, #75).
* Switch reference types (#69, #72).
* Add ``Result`` utility (#58).
* Add an option to disable certificate verification (#59).
* Add secretary token (#64).
* Add sender specific processors (#66).
* Add email headers processor (#65).
* Add options for server limits (#48).
* Fix SQLAlchemy 2.0 deprecation warnings (#68).
* Mark ScalarListType cacheable (#71).
* Resolve frgal warnings (#74).
* Flush objects at the end of session in tests (#30).
* Update project setup.

0.4.0 (2022-04-06)
------------------

* Switch to API 1.2 (#50).
* Add ``multi_send`` to email servicer (#51).
* Add batch send to email servicer (#53).
* Add a resend script.

0.3.1 (2022-03-28)
------------------

* Set ``MIME-Version`` header on S/MIME emails (#49).

0.3.0 (2022-03-03)
------------------

* Use new UID format (#43).
* Refactor S/MIME signatures to use cryptography (#31).
* Shorten a length of an ``Email`` string representation (#14).
* Log summaries of operations (#10).
* Add script to send a message.
* Add test utils for commands (#24).
* Fix manual page for archive (#28).
* Increase coverage.
* Make mypy more strict and fix annotations.
* Update project setup.
* Add issue template.

0.2.2 (2022-02-23)
------------------

* Send messages using round-robin by type (#32).
* Expect non-multipart email in delivery (#36).
* Expect headers of undelivered message (#37).
* Handle exceptions in delivery processing (#38).

0.2.1 (2022-01-20)
------------------

* Delete references on clean (#29).

0.2.0 (2022-01-12)
------------------

* Add support for python 3.10.
* Drop support for python 3.6.
* Drop support for SQLAlchemy 1.3 (#7).
  * Replace deprecated ``has_table`` method.
* Fix comments on address country (#2).
* Drop ``SmsMessage.msisdn`` (#5).
* Fix section of man pages (#12).
* Add gRPC reflection (#1).
* Enable multiple ``--type`` options (#19).
* Support undelivered messages in backends (#21).
* Fail on defect in recipient's email address (#23).
* Add ``--from`` and ``--to`` to ``archive`` command (#22).
* Add ``--format`` to ``monitor`` command (#25).
* Rename ``load_instance`` args (#26).
* Rename type to method in code (#27).
* Update static checks.

0.1.0 (2021-12-13)
------------------

Initial version.

* Support emails, SMS and letters.
* Include message archive.
* Include migration of FRED message archives.
* Support blocked addresses.
* Provides email senders and delivery checks.
* SMS and letter senders are supported, but no particular backends are implemented.
