ae.notify

send notifications via email, telegram or whatsapp

this pure python module depends mainly on the Standard Python Libraries email and smtplib and the external requests module.

an instance of the Notifications has to be created for each notification sender in your app, providing the sender’s credentials for each used notification channel (service).

the notification channels and the receiver(s) can be specified individually for each notification message to send.

Module Attributes

`DEF_ENC_PORT`	standard SMTP port
`DEF_ENC_SERVICE_NAME`	standard SMTP service name
`SSL_ENC_PORT`	port to use SMTP via SSL
`SSL_ENC_SERVICE_NAME`	service name in `Notifications.smtp_server_uri` of SMTP via SSL
`TLS_ENC_PORT`	port to use SMTP via TLS
`TLS_ENC_SERVICE_NAME`	service name in `Notifications.smtp_server_uri` of SMTP via TLS
`TELEGRAM_MESSAGE_MAX_LEN`	maximum length of Telegram notification message body
`WHATSAPP_MESSAGE_MAX_LEN`	maximum length of Whatsapp notification message body

Classes

Notifications([smtp_server_uri, mail_from, ...])

a single instance of this class can be used to handle all notifications of an app/service.

DEF_ENC_PORT = 25: standard SMTP port

DEF_ENC_SERVICE_NAME = 'smtp': standard SMTP service name

SSL_ENC_PORT = 465: port to use SMTP via SSL

SSL_ENC_SERVICE_NAME = 'smtps': service name in Notifications.smtp_server_uri of SMTP via SSL

TLS_ENC_PORT = 587: port to use SMTP via TLS

TLS_ENC_SERVICE_NAME = 'smtpTLS': service name in Notifications.smtp_server_uri of SMTP via TLS

TELEGRAM_MESSAGE_MAX_LEN = 4096: maximum length of Telegram notification message body

WHATSAPP_MESSAGE_MAX_LEN = 65536: maximum length of Whatsapp notification message body

_body_mime_type_conversion(msg_body, mime_type)[source]

convert content of notification message body.

Parameters:

msg_body¶ (str) – message body string.
mime_type¶ (str) – mime type to convert to, if it has the “to” prefix in front of the resulting mime type.

Return type:

Tuple[str, str]

Returns:

tuple of converted message body and resulting mime type (removing the “to” prefix).

class Notifications(smtp_server_uri='', mail_from='', local_mail_host='', telegram_token='', whatsapp_token='', whatsapp_sender='')[source]

Bases: object

a single instance of this class can be used to handle all notifications of an app/service.

__init__(smtp_server_uri='', mail_from='', local_mail_host='', telegram_token='', whatsapp_token='', whatsapp_sender='')[source]

initialize one or more different services for a sender of multiple notifications to individual receivers.

Parameters:

smtp_server_uri¶ (str) – host and optional port and user credentials of email SMTP server to use, in the format [service://][user[:password]@]mail_server_host[:mail_server_port]. default SMTP ports: 25/DEF_ENC_PORT, port 587/TSL_ENC_PORT for E-SMTP/TLS or 465/SSL_ENC_PORT for smtps/SSL.
mail_from¶ (str) – email sender address.
local_mail_host¶ (str) – FQDN of the local email host in the SMTP HELO/EHLO command.
telegram_token¶ (str) – token for the Telegram cloud API obtained from the @BotFather bot.
whatsapp_token¶ (str) – token for the WhatsApp cloud API obtained from the developer portal.
whatsapp_sender¶ (str) – sender phone number id for the WhatsApp cloud API obtained from the developer portal.

send_notification(msg_body, receiver, subject='', mime_type='to_html')[source]

send a notification message with optional subject to receiver via the specified service.

Parameters:

msg_body¶ (str) – message body. line breaks are converted (br-tag <-> newline character) in accordance with mime_type.
receiver¶ (str) – receiver address in the format service:address=name, where service is mailto, telegram or whatsapp, address is an email address, a chat id or phone number and name is the name of the receiving person.
subject¶ (str) – optional subject text. added to the top of the msg_body for messenger services, separated by an empty line. if not specified or specified as empty string or as a single space character, then it will not be added to the top of the message body.
mime_type¶ (str) – mime type (‘html’ or ‘plain’), and optional conversion to it (if starts with ‘to’).

Return type:

str

Returns:

error message on error or empty string if notification got send successfully.

send_email(msg_body, address, subject, name, mime_type='to_html')[source]

send email to the passed address.

Parameters:

msg_body¶ (str) – message body text. for new lines use newline char in plain and <br> in html mime_type.
address¶ (str) – email address of the receiver.
subject¶ (str) – email subject text.
name¶ (str) – name of the receiver.
mime_type¶ (str) – mime type (‘html’ or ‘plain’), and optional conversion to it (if starts with ‘to’).

Return type:

str

Returns:

error message on error or empty string if notification email got send successfully.

send_telegram(msg_body, chat_id, name, mime_type='to_html')[source]

send message to the passed telegram chat id.

Parameters:

msg_body¶ (str) – message body text. in ‘html’ mime_type message texts are only a few tags support by Telegram (see https://core.telegram.org/bots/api#html-style). on top of that you can also include the following tags, which will be either converted or removed: * br: will be converted into a new line character. * div: will be removed.
chat_id¶ (str) – chat id of the telegram receiver or group.
name¶ (str) – name of the receiver.
mime_type¶ (str) – mime type (‘html’ or ‘plain’), and optional conversion to it (if starts with ‘to’).

Return type:

str

Returns:

error message on error or empty string if notification got send successfully.

Hint

see https://www.heise.de/select/ct/2023/8/2231816070982959290 for useful bots and tips. use https://telemetr.io/, https://lyzem.com/ or https://tgstat.com/ to search/find public channels/groups.

send_whatsapp(msg_body, receiver_id, name, mime_type='to_html')[source]

send message to the passed WhatsApp user/group.

Parameters:

msg_body¶ (str) – message body text. for new lines use newline char in plain and <br> in html mime_type.
receiver_id¶ (str) – phone number with country code (and a leading ‘+’) of the WhatsApp receiver or the id of the WA group (last part of the URL to invite somebody into the group).
name¶ (str) – name of the receiver.
mime_type¶ (str) – mime type (‘html’ or ‘plain’), and optional conversion to it (if starts with ‘to’). recognized/converted html tags are b, br, i and pre.

Return type:

str

Returns:

error message on error or empty string if notification got send successfully.

using WA Business API (see: https://developers.facebook.com/docs/whatsapp/on-premises/reference/messages and https://github.com/Neurotech-HQ/heyoo/blob/58ad576c3dfaf05bad5f342bc8614cf0ba02e6ae/heyoo/__init__.py#L43) has the restriction that the receiver has first to send a message to the sender to get a window of 24 hours. and using pyWhatKit’s webbrowser-based approach will not work on PythonAnywhere because web.whatsapp.com is not in their whitelist (https://www.pythonanywhere.com/whitelist/)