smtp – SMTP Services Components Module

Email (SMTP) services for Kofa.

Note About Encodings

All functions in this module expect any raw strings passed in to be encoded ‘utf-8’ (if you pass in unicode objects instead, this is not a problem).

This is because we cannot easily tell from a raw string (it is in fact only a byte stream) what encoding it has. In latin-1 and utf-8, for instance, there exist some chars (byte values) that have different meanings in both encodings. If we see such a char in a byte stream: what is it meant to represent? The respective character from latin1 or the one from utf-8?

We therefore interpret all internally used raw strings to be encoded as utf-8.

The functions in here nevertheless try hard to produce output (mail parts, headers, etc.) encoded in the least complex manner. For instance if you pass in some address or mail body that is representable (correctly) as ASCII or latin-1, we will turn the text into that encoding (given, you passed it in as utf-8) to stay as compatible as possible with old mailers that do not understand utf-8.

class waeup.kofa.smtp.DefaultMailService

Bases: grokcore.component.components.GlobalUtility

Returns a zope.sendmail.IMailDelivery.

Searches a site from current request (if applicable) and returns the mail delivery set for this site or a fake mailer that does not really send mail (for testing, evaluating, etc.).

__call__()

__doc__ = 'Returns a :class:`zope.sendmail.IMailDelivery`.\n\n Searches a site from current request (if applicable) and returns\n the mail delivery set for this site or a fake mailer that does not\n really send mail (for testing, evaluating, etc.).\n '

__implemented__ = <implementedBy waeup.kofa.smtp.DefaultMailService>

__module__ = 'waeup.kofa.smtp'

__provides__

Special descriptor for class __provides__

The descriptor caches the implementedBy info, so that we can get declarations for objects without instance-specific interfaces a bit quicker.

For example:

>>> from zope.interface import Interface
>>> class IFooFactory(Interface):
...     pass
>>> class IFoo(Interface):
...     pass
>>> class C(object):
...     implements(IFoo)
...     classProvides(IFooFactory)
>>> [i.getName() for i in C.__provides__]
['IFooFactory']

>>> [i.getName() for i in C().__provides__]
['IFoo']

waeup.kofa.smtp.FROM_ADDRESS = 'no-reply@waeup.org'

The hardcoded from address. Must not by yahoo.com.

class waeup.kofa.smtp.FakeSMTPDelivery

Bases: grokcore.component.components.GlobalUtility

A fake mail delivery for testing etc.

Instead of sending real mails, this mailer only logs received messages to the test.smtp logger.

__doc__ = 'A fake mail delivery for testing etc.\n\n Instead of sending real mails, this mailer only logs received\n messages to the ``test.smtp`` logger.\n '

__implemented__ = <implementedBy waeup.kofa.smtp.FakeSMTPDelivery>

__module__ = 'waeup.kofa.smtp'

__provides__

Special descriptor for class __provides__

The descriptor caches the implementedBy info, so that we can get declarations for objects without instance-specific interfaces a bit quicker.

For example:

>>> from zope.interface import Interface
>>> class IFooFactory(Interface):
...     pass
>>> class IFoo(Interface):
...     pass
>>> class C(object):
...     implements(IFoo)
...     classProvides(IFooFactory)
>>> [i.getName() for i in C.__provides__]
['IFooFactory']

>>> [i.getName() for i in C().__provides__]
['IFoo']

send(fromaddr, toaddrs, message)

waeup.kofa.smtp.encode_address(addr, name=u'')

Turn email address parts into a single valid email string.

The given email address and the name are turned into a single (byte stream) string, suitable for use with To: or From: headers in emails.

Any encodings to a mailer-readable format are performed.

Preferred input format is unicode, although also raw strings (byte streams) work as long as they are decodable from UTF-8.

That means: if you pass in non-unicode string, take care to deliver utf-8 encoded strings (or plain ASCII).

Returns a single (raw) string like “My Name <my@sample.com>”.

waeup.kofa.smtp.encode_body(text)

Build MIME message part from text.

You can pass unicode objects or simple strings as text.

If the input is a simple string, this string is expected to be encoded ‘utf-8’!

Returns a MIMEText object.

waeup.kofa.smtp.encode_header_item(item)

Turns item, a string into an SMTP header part string.

Encodings are checked carefully (we try to encode as ASCII, Latin-1 and UTF-8 in that order).

If item is not a basestring, None is returned.

waeup.kofa.smtp.send_mail(from_name, from_addr, rcpt_name, rcpt_addrs, subject, body, config=None, cc=None, bcc=None)

Send mail.

Use IMailService to send a mail with the parameters delivered.

Please note: the from_addr given will be used for the reply-to (and cc) field only. It will _not_ be used for the from field, as yahoo does not allow non-yahoo servers to deliver mail with @yahoo.com in the from-field.

The from-address set here will be: FROM_ADDRESS as set above.

XXX: The hard-coded from-address should be changable or be

determined smarter by looking up a FQDN or similar.