linkahead.utils.email module

exception linkahead.utils.email.SendEmailException(msg)

Bases: LinkAheadException

linkahead.utils.email.send_email(message: EmailMessage | str, to: str | list[str] | None = None, from_address: str | None = None, **kwargs)

Send an email to the configured smtp server.

The relevant options in the pylinkahead.ini are:

[Email] # required smtp_server=smtp.example.com smtp_port=587

# optional smtp_starttls=yes smtp_username=your_username smtp_password=your_password from_address=LA <la@example.com> bcc_append=LA <logmail@example.com>, LA2 <logmail2@example.com>

See schema-pylinkahead-ini.yaml for more options. All of the following smtp_*, from_address, and bcc_append are supported as well.

Parameters:

• message (str | email.message.EmailMessage) – The message to be send. This can be a plain string (for plain text email) or a EmailMessage object which then also may be a mixed/multipart email with attachments or HTML content.

• to (str | list of str) – The recipient’s RFC 5321 compliant email address(es). Sets/overrides the mail’s “To” header which is a mandatory header.

• from_address (str) – The sender’s RFC 5321 compliant email address. Sets/overrides the mail’s “From” header. You may set a global fallback in the pylinkahead.ini, [Email][from_address].

• **kwargs –

  For setting the email headers:

  subjectstr

  Subject of the email. Sets the mail’s “Subject” header. Ignored, if message is an EmailMessage.

  ccstr | list of str

  Single or list of cc-recipients. Sets the mail’s “CC” header. Ignored, if message is an EmailMessage.

  bccstr | list of str | None

  Single or list of bcc-recipients. Sets the mail’s “BCC” header. However, the bcc_append list is applied afterwards in any case. Ignored, if message is an EmailMessage.

  bcc_appendstr | list of str | None

  Comma-separated list of BCC addresses, these are being appended to the BCC header. This option also allows to just ignore the pylinkahead.ini’s value by passing an empty list/empty string. Defaults to the values from the pylinkahead.ini or None

  For defining the connection to the SMTP server. The options are required and must be present either here or in the pylinkahead.ini:

  smtp_serverstr

  Hostname of the SMTP server. Don’t include the URI scheme (“smtp://” or “smtps://”) nor the port.

  smtp_portint

  Port of the SMTP server, 0<smtp_port<65536.

  Further options for the SMTP connection:

  smtp_usernamestr

  Username to authenticate with the SMTP server. Defaults to None

  smtp_passwordstr

  Username to authenticate with the SMTP server. Defaults to None

  smtp_auth_no_tls_servers: list of str

  Allow the client to send credentials over a non-tls/non-starttls connection but only for these hostnames. This is a potentially dangerous option when sending credentials over an untrusted network such as the internet. Ignored if smtp_username or smtp_password are falsy or if smtp_tls or smtp_starttls are True. Defaults to [“localhost”, “127.0.0.1”].

  smtp_tlsbool

  Whether to use TLS (normal TLS, not STARTTLS). If this is True, smtp_starttls will be ignored. Defaults to False

  smtp_starttlsbool

  Whether to use STARTTLS. Ignored if smtp_tls is True. Defaults to False.

  smtp_tls_verifybool

  Whether to verify the certificate during TLS/STARTTLS handshakes. Ignored if neither is being used. Defaults to True

  smtp_tls_check_hostnamebool | None

  Whether to check the server’s hostname during TLS/STARTTLS handshakes. Ignored if neither is being used. Implies smtp_tls_verify=True if this is True. Defaults to None which effectively means use the value of smtp_tls_verify

  smtp_tls_cacert: str

  Path to local file containing (a chain of) TLS certificates of trusted CAs (certification authorities)

  smtp_timeoutfloat

  Timeout in seconds for creating the SMTP connection. None or <=0 means system default. Must survive casting to float. Defaults to None

Raises:

• linkahead.ConfigurationError : – If any required smtp setting is missing from both the pylinkahead.ini and the parameter.

• ValueError : –

  • If to is None and message is a plain string. * If old API’s parameters are passed, such as “send_mail_bin” or “body”.

• TimeoutError : – On timeouts.

• linkahead.SendEmailException : – SSL errors, Authentication errors, etc.