Documentation: some more examples for common use cases (adding extra headers)

[lbeltrame]

I'm opening this as an issue so it's tracked. In particular, it would be nice to have in the docs some indication on how to add extra headers for common operations like Disposition-Notification-To. I had to hunt down the API docs and I couldn't quite get them to work (malformed email addresses).

So, a little example in the documentation would help a lot.

[aspineux]

Hello
You can access the API documentation from here

http://www.magiksys.net/pyzmail/api/pyzmail-module.html

Most of the functions have a doc_string with a lot of information. For the the headers, see :

http://www.magiksys.net/pyzmail/api/pyzmail.generate-module.html#complete_mail

Their is a sample :

payload, mail_from, rcpt_to, msg_id=complete_mail(msg, ('Me', 'me@foo.com'),
... [ ('Him', 'him@bar.com'), ], 'Non unicode subject', 'iso-8859-1',
... cc=['her@bar.com',], date=1313558269, headers=[('User-Agent', u'pyzmail'), ])

that show how to add custom headers. compose_mail() call build_mail() and complete_mail()

Most information that are not in the short documentation pages are in the API documentation (but you already know that :-) ). And you can read the source for more.

Hope this help.

I'm sorry, I will not change the documentation for this because the information is available in the API documentation.

Thanks for using pyzmail.

Regards

[lbeltrame]

I disagree: I followed the API docs, yet it generated a completely wrong header for Disposition-Notification-To.

Code:

formatted_receipt_addr = format_addresses(
    ['name.surname@example.org'],
    "Disposition-Notification-To",
    "utf-8").encode()

extra_headers = [("Disposition-Notification-To", formatted_receipt_addr)]

# later on... ENCODING is utf-8
mail_structure = compose_mail(sender, recipients, subject, ENCODING,
                                  (text, ENCODING), html=None,
                                  attachments=attachments,
                                  headers=extra_headers,
                                  bcc=bcc)

However this creates a completely wrong header:

Disposition-Notification-To: =?utf-8?q?name=2Esurnamei=40example=2Eorg?@server.hostname.example.org

I likely did something wrong, but I just followed the API docs.

[aspineux]

pyzmail don't support what you want to do :-(
The header value is expected to be a unicode string, not an already encoded string.

I have pushed a fix to support email.header.Header instances in the header.
Please update your generate.py with the last one on github and try this :

formatted_receipt_addr = format_addresses(
['name.surname@example.org'],
"Disposition-Notification-To",
"utf-8")

without the .encode() at the end.