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:
objectA file attached to an email.
- __init__(filename, content, content_type='text/plain')
- class smarter.apps.infrastructure.services.email.EmailService(provider_name, *args, **kwargs)[source]
Bases:
InfrastructureServiceThe platform’s outgoing email.
- static admin_bcc(recipients)[source]
The blind copy to the platform’s admin,
smarter_settings.email_admin.
- error_class
alias of
EmailServiceError
- message(subject, body, to, html=False, from_email=None, attachments=None, headers=None)[source]
Return a message, from
smarter_settings.smtp_from_emailunlessfrom_emailis given.It has no
Bccheader: blind copies are added to the envelope by_deliver(). A message with attachments ismultipart/mixed, with the body as its first part.headersare added after the standard ones, e.g.List-Unsubscribe.- Return type:
- 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, withmasked_recipients().- Parameters:
subject (
str) – The subject.body (
str) – The body, HTML ifhtmlis 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 defaultsmarter_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:
- Returns:
True if the email was sent.
- service_name: str = 'email'
The name of the service in signals and logs, see
InfrastructureServiceNames.
- class smarter.apps.infrastructure.services.email.InMemoryEmailService(ready=True, **kwargs)[source]
Bases:
EmailServiceEmail that is kept in
outbox, for tests and local development.- Parameters:
ready (
bool) – Whether the service is ready.
- fail
Set to make delivery fail with this error.
- class smarter.apps.infrastructure.services.email.SMTPEmailService(allow_in_tests=False, smtp_class=<class 'smtplib.SMTP'>, **kwargs)[source]
Bases:
EmailServiceEmail, with SMTP, configured by the
smtp_*settings ofsmarter_settings.In the unit tests, nothing is sent, unless
allow_in_testsis True, so that tests never email real people.- Parameters:
- 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:
- class smarter.apps.infrastructure.services.email.SentEmail(subject, sender, recipients, bcc=<factory>, body='', headers=<factory>, attachments=<factory>)[source]
Bases:
objectAn email that
InMemoryEmailServicesent.- __init__(subject, sender, recipients, bcc=<factory>, body='', headers=<factory>, attachments=<factory>)
- attachments: list[EmailAttachment]
- 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:
- smarter.apps.infrastructure.services.email.get_email()[source]
Return the email service, which is created once.
- Return type:
- 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.