Email Service

The email service: the platform’s outgoing email.

Email does not depend on a cloud: Smarter sends it with SMTP, to any SMTP server, e.g. AWS Simple Email Service’s. So EmailService is implemented by SMTPEmailService, for every cloud provider, and an email API, e.g. a cloud’s, would be another implementation.

The platform uses it through smarter.apps.infrastructure.services.infrastructure .email. Tests replace it with configure_email(), e.g. with InMemoryEmailService.

from smarter.apps.infrastructure.services import infrastructure

infrastructure.email.send_email(subject="Welcome!", body="<p>Hello</p>", to="user@example.com", html=True)

Files are attached with EmailAttachment:

attachment = EmailAttachment(filename="job.log", content=log.encode("utf-8"))
infrastructure.email.send_email(subject="Job log", body="Attached.", to="ops@example.com", attachments=[attachment])

Recipients’ addresses are never logged in full: they are masked with masked_recipients().

class smarter.apps.infrastructure.services.email.EmailAttachment(filename, content, content_type='text/plain')[source]

Bases: object

A file attached to an email.

__init__(filename, content, content_type='text/plain')
content: bytes

The file’s contents.

content_type: str = 'text/plain'

The file’s MIME type, e.g. text/plain or application/gzip.

filename: str

The file’s name, as the recipient sees it.

mime_part()[source]

Return the attachment as a base64-encoded MIME part.

Return type:

MIMEBase

Returns:

The MIME part, with a Content-Disposition: attachment header.

class smarter.apps.infrastructure.services.email.EmailService(provider_name, *args, **kwargs)[source]

Bases: InfrastructureService

The platform’s outgoing email.

static admin_bcc(recipients)[source]

The blind copy to the platform’s admin, smarter_settings.email_admin.

Parameters:

recipients (list[str]) – The email’s recipients, who need no copy.

Return type:

list[str]

Returns:

The admin’s address, or nothing if there is no valid admin address, or the admin is a recipient.

error_class

alias of EmailServiceError

log_not_sent(subject, to)[source]

Log an email that was not sent because the service is not ready.

Parameters:
  • subject (str) – The email’s subject.

  • to (str | List[str]) – The email’s recipients, which are logged masked.

Return type:

None

message(subject, body, to, html=False, from_email=None, attachments=None, headers=None)[source]

Return a message, from smarter_settings.smtp_from_email unless from_email is given.

It has no Bcc header: blind copies are added to the envelope by _deliver(). A message with attachments is multipart/mixed, with the body as its first part. headers are added after the standard ones, e.g. List-Unsubscribe.

Return type:

MIMEMultipart

send_email(subject, body, to, html=False, from_email=None, quiet=False, bcc_admin=True, attachments=None, headers=None)[source]

Send an email.

Failures are logged, and announced with email_failed, rather than raised, so that email never breaks the request that sends it. The recipients are logged masked, with masked_recipients().

Parameters:
  • subject (str) – The subject.

  • body (str) – The body, HTML if html is True.

  • to (str | List[str]) – The recipient, or recipients. Invalid addresses are dropped.

  • html (bool) – True if the body is HTML.

  • from_email (str | None) – The sender, by default smarter_settings.smtp_from_email.

  • quiet (bool) – True to only log what would have been sent.

  • bcc_admin (bool) – Send a blind copy to the platform’s admin, smarter_settings.email_admin. Pass False for an email that carries a secret, e.g. a password reset link, which only its recipient may see.

  • attachments (List[EmailAttachment] | None) – Files to attach. The message’s size, attachments included, is limited by the SMTP server, e.g. 10 MB for AWS Simple Email Service.

  • headers (dict[str, str] | None) – More headers, e.g. {"List-Unsubscribe": "<https://...>"}.

Return type:

bool

Returns:

True if the email was sent.

service_name: str = 'email'

The name of the service in signals and logs, see InfrastructureServiceNames.

static validate_mail_list(emails, quiet=False)[source]

Return the valid email addresses of a list.

Parameters:
  • emails (str | List[str]) – An email address, or a list of them.

  • quiet (bool) – True to not log invalid addresses.

Return type:

List[str] | None

Returns:

The valid addresses, or None if there are none.

class smarter.apps.infrastructure.services.email.InMemoryEmailService(ready=True, **kwargs)[source]

Bases: EmailService

Email that is kept in outbox, for tests and local development.

Parameters:

ready (bool) – Whether the service is ready.

__init__(ready=True, **kwargs)[source]
fail

Set to make delivery fail with this error.

property ready: bool

Whether the service is ready, as set in the constructor.

class smarter.apps.infrastructure.services.email.SMTPEmailService(allow_in_tests=False, smtp_class=<class 'smtplib.SMTP'>, **kwargs)[source]

Bases: EmailService

Email, with SMTP, configured by the smtp_* settings of smarter_settings.

In the unit tests, nothing is sent, unless allow_in_tests is True, so that tests never email real people.

Parameters:
  • allow_in_tests (bool) – Send email in the unit tests.

  • smtp_class (Callable[..., SMTP]) – The SMTP client class, e.g. a fake.

__init__(allow_in_tests=False, smtp_class=<class 'smtplib.SMTP'>, **kwargs)[source]
log_not_sent(subject, to)[source]

Log an email that was not sent, with instructions for configuring SMTP.

SMTP is optional, so this is logged for each email that is not sent, rather than raised. In the unit tests, where email is never sent, a one-line warning is logged instead. The recipients are logged masked.

Return type:

None

property ready: bool

Whether SMTP is configured.

Always False in the unit tests, unless allow_in_tests.

class smarter.apps.infrastructure.services.email.SentEmail(subject, sender, recipients, bcc=<factory>, body='', headers=<factory>, attachments=<factory>)[source]

Bases: object

An email that InMemoryEmailService sent.

__init__(subject, sender, recipients, bcc=<factory>, body='', headers=<factory>, attachments=<factory>)
attachments: list[EmailAttachment]
bcc: list[str]
body: str = ''
headers: dict[str, str]
recipients: list[str]
sender: str
subject: str
smarter.apps.infrastructure.services.email.configure_email(factory)[source]

Set the factory of the email service that get_email() returns.

Parameters:

factory (Callable[[], EmailService] | None) – Returns the service, or None to restore the default, SMTPEmailService.

Return type:

None

smarter.apps.infrastructure.services.email.get_email()[source]

Return the email service, which is created once.

Return type:

EmailService

smarter.apps.infrastructure.services.email.masked_recipients(recipients)[source]

Return email addresses masked for the logs, with mask_email().

Smarter’s logs never hold a person’s email address. The masked form, e.g. j****@example.com, still tells recipients apart by their first character and domain.

Parameters:

recipients (str | Iterable[str] | None) – An address, a list or set of addresses, or None.

Return type:

list[str]

Returns:

The masked addresses, in the order that they were given.