Mail Bundle¶

Integrates Flask Mail with Flask Unchained.

Installation¶

Install dependencies:

pip install "flask-unchained[mail]"

And enable the bundle in your unchained_config.py:

# your_project_root/unchained_config.py

BUNDLES = [
    # ...
    'flask_unchained.bundles.mail',
    'app',
]

NOTE: If you have enabled the Celery Bundle, and want to send emails asynchronously using Celery, then you must list the celery bundle after the mail bundle in BUNDLES.

Config¶

class flask_unchained.bundles.mail.config.Config[source]

Default configuration options for the mail bundle.

MAIL_SERVER = '127.0.0.1': The hostname/IP of the mail server.

MAIL_PORT = 25: The port the mail server is running on.

MAIL_USERNAME = None: The username to connect to the mail server with, if any.

MAIL_PASSWORD = None: The password to connect to the mail server with, if any.

MAIL_USE_TLS = False: Whether or not to use TLS.

MAIL_USE_SSL = False: Whether or not to use SSL.

MAIL_DEFAULT_SENDER = 'Flask Mail <noreply@localhost>': The default sender to use, if none is specified otherwise.

MAIL_SEND_FN(to: Union[str, List[str], None] = None, template: Optional[str] = None, **kwargs)

The function to use for sending emails. Defaults to _send_mail(). Any customized send function must implement the same function signature:

def send_mail(subject_or_message: Optional[Union[str, Message]] = None,
              to: Optional[Union[str, List[str]] = None,
              template: Optional[str] = None,
              **kwargs):
    # ...

NOTE: subject_or_message is optional because you can also pass subject as a keyword argument, and to is optional because you can also pass recipients as a keyword argument. These are artifacts of backwards-compatibility with vanilla Flask-Mail.

MAIL_DEBUG = 0: The debug level to set for interactions with the mail server.

MAIL_MAX_EMAILS = None: The maximum number of emails to send per connection with the mail server.

MAIL_SUPPRESS_SEND = False: Whether or not to actually send emails, or just pretend to. This is mainly useful for testing.

MAIL_ASCII_ATTACHMENTS = False: Whether or not to coerce attachment filenames to ASCII.

class flask_unchained.bundles.mail.config.DevConfig[source]

Development-specific config options for the mail bundle.

MAIL_DEBUG = 1: Set the mail server debug level to 1 in development.

MAIL_PORT = 1025: In development, the mail bundle is configured to connect to MailHog.

class flask_unchained.bundles.mail.config.ProdConfig[source]

Production-specific config options for the mail bundle.

MAIL_PORT = 465: In production, the mail bundle is configured to connect using SSL.

MAIL_USE_SSL = True: Set use SSL to True in production.

class flask_unchained.bundles.mail.config.TestConfig[source]

Test-specific config options for the mail bundle.

MAIL_SUPPRESS_SEND = True: Do not actually send emails when running tests.

Usage¶

After configuring the bundle, usage is simple:

from flask_unchained.bundles.mail import mail

mail.send_message('hello world', to='foo@bar.com')

mail is an instance of the Mail extension, and send_message() is the only public method on it. Technically, it’s an alias for send(), which you can also use. (The send() method is maintained for backwards compatibility with the stock Flask Mail extension, although it has a different but compatible function signature than the original - we don’t require that you manually create Message instances yourself before calling send().)

Commands¶

flask mail¶

Mail commands.

flask mail COMMAND [<args>...] [OPTIONS]

send-test-email¶

Attempt to send a test email to the given email address.

flask mail send-test-email [OPTIONS]

Options

--to <to>¶: Email address of the recipient.

--subject <subject>¶: Email subject.

pytest fixtures¶

The mail bundle includes one pytest fixture, outbox(), that you can use to verify that emails were sent:

def test_something(client, outbox):
    r = client.get('endpoint.that.sends.an.email')
    assert len(outbox) == 1
    assert outbox[0].subject == 'hello world'
    assert 'hello world' in outbox[0].html

API Docs¶

See Mail Bundle API