Documentation for logging and error checking is amiss

[metaperl]

hello,

The documentation for this library does not show any way to enable logging.

Currently, email is not being delivered and I have no idea why - the ability to enable logging would be of great use.

Also the docs do not indicate the return value of methods, so I have no idea how to see if each method call is working.

My usage of this module is very minimal. All of it is shown here

[sh4d0v1]

Documentation about the return value especially of the send() function would be very nice.

Of course the function can't return if the mail successfully arrived at the recipients mailbox, but it could tell if the mail was handed to the SMTP server successfully.

[amcgregor]

Official documentation, as logging is universal Python functionality, not custom or specific to this package.

The return value of send() calls will depend on the context in which you are invoking that method and the particular configuration you are utilizing:

• The ImmediateManager will bubble back up the transport's deliver() return value.

• Futures-based managers (e.g. FuturesManager or DynamicManager) return the Future receipt instance for the background scheduled task. To perform some action upon completion (e.g. verify or validate delivery), register a "done callback". Official Python documentation.

• The SMTP transport has no return value for its deliver call. Instead, it utilizes exceptions to notify of exceptional statuses. (One of: MessageFailedException with reason string argument also logged at the error or warning levels, or TransportFailedException logged at the warning level.) When using a Futures-based background manager, always remember to define a done callback that, at a minimum, requests the future.result() to permit the exception to actually explode, otherwise background execution will eat all exceptions.

• Other transports similarly return nothing (e.g. Amazon SES, Sendmail Popen, SendGrid, MBox, Mailgun, …) excluding MockTransport which returns True or False (mocked success or failure). They all use exceptions to notify of exceptional issues, e.g. the Mailgun transport may bubble a Requests exception due to the raise_for_status call.

• The base Mailer interface (the typical entry point for configuration and use) does return whatever is returned by the manager. Similarly, the Message.send helper method also returns the result of the send call on the bound Mailer instance.