core.mail
=========

.. py:module:: core.mail


Attributes
----------

.. autoapisummary::

   core.mail.specials_regex
   core.mail.alphanumeric
   core.mail.qp_prefix
   core.mail.qp_suffix
   core.mail.QP_PREFIX_LENGTH
   core.mail.QP_SUFFIX_LENGTH
   core.mail.QP_MAX_WORD_LENGTH
   core.mail.QP_CONTENT_LENGTH


Classes
-------

.. autoapisummary::

   core.mail.Attachment


Functions
---------

.. autoapisummary::

   core.mail.needs_qp_encode
   core.mail.qp_encode_display_name
   core.mail.coerce_address
   core.mail.format_single_address
   core.mail.format_address
   core.mail.prepare_email


Module Contents
---------------

.. py:data:: specials_regex

.. py:data:: alphanumeric
   :value: 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789'


.. py:data:: qp_prefix
   :value: '=?utf-8?q?'


.. py:data:: qp_suffix
   :value: '?='


.. py:data:: QP_PREFIX_LENGTH
   :value: 10


.. py:data:: QP_SUFFIX_LENGTH
   :value: 2


.. py:data:: QP_MAX_WORD_LENGTH
   :value: 75


.. py:data:: QP_CONTENT_LENGTH
   :value: 63


.. py:function:: needs_qp_encode(display_name: str) -> bool

.. py:function:: qp_encode_display_name(display_name: str) -> str

   Applies Quoted Printable encoding to the display name according
   to Postmark API's rules that can be parsed losslessly back into
   the original display_name with the EmailMessage API.


.. py:function:: coerce_address(address: email.headerregistry.Address | str) -> email.headerregistry.Address

   Coerces a string type into a email.headerregistry.Address object
   by parsing the string as a sender header.

   It acts like parseaddr for string values, but undoes QP-encoding
   for the display_name which parseaddr does not.

   NOTE: This function should probably go away, once we switch to
         using Address objects everywhere. Or we make it more strict
         by asserting that string values need to be an email address
         without display_name, so we can use Address(addr_spec=address)
         to coerce it, which should be faster than header_factory.


.. py:function:: format_single_address(address: email.headerregistry.Address | str) -> str

   Formats a single Address according to Postmark API rules that is
   cross-compatible with email.message.EmailMessage for raw SMTP sends.

   The rules state that backslash escaping quotes is illegal and quoted
   printable encoded display names need to be split into space-separated
   encoded words of maximum length 75, with the entire display name
   enclosed in double quotes if it contains more than one word.

   :param address: email.headerregistry.Address or preformatted string


.. py:function:: format_address(addresses: core.types.SequenceOrScalar[email.headerregistry.Address | str]) -> str

   Convenience function that accepts both a single Address and a
   sequence of Address, otherwise identical to format_single_address

   It enforces a limit of 50 addresses, due to Postmark API restrictions

   :param addresses: Single Address/str or sequence thereof


.. py:class:: Attachment(filename: _typeshed.StrPath, content: _typeshed.SupportsRead[str | bytes] | str | bytes | None = None, content_type: str | None = None)

   Represents a mail attachment that can be passed to prepare_email


   .. py:attribute:: __slots__
      :value: ('filename', 'content', 'content_type')



   .. py:attribute:: filename
      :type:  str


   .. py:attribute:: content
      :type:  bytes


   .. py:attribute:: content_type
      :type:  str


   .. py:method:: prepare() -> core.types.AttachmentJsonDict

      Prepares attachment so it can be sent to Postmark API.



.. py:function:: prepare_email(sender: email.headerregistry.Address | str, reply_to: email.headerregistry.Address | str | None = None, receivers: core.types.SequenceOrScalar[email.headerregistry.Address | str] = (), cc: core.types.SequenceOrScalar[email.headerregistry.Address | str] = (), bcc: core.types.SequenceOrScalar[email.headerregistry.Address | str] = (), subject: str | None = None, content: str | None = None, plaintext: str | None = None, attachments: collections.abc.Iterable[Attachment | _typeshed.StrPath] = (), headers: dict[str, str] | None = None, stream: str = 'marketing') -> core.types.EmailJsonDict

   Creates a dictiornary that can be turned into JSON as is and sent
   to the Postmark API.

   :param content: HTML content.
   :param attachments: Either a list of :class:`onegov.core.email.Attachment`
       or a list of filenames/os.PathLike to attach to the email.
   :param headers: Dictionary containing additional headers to be set