djblets.mail.message¶

E-mail message composition and sending.

class EmailMessage(subject='', text_body='', html_body='', from_email=None, to=None, cc=None, bcc=None, sender=None, in_reply_to=None, headers=None, auto_generated=False, prevent_auto_responses=False, from_spoofing=None, enable_smart_spoofing=None)¶

Bases: EmailMultiAlternatives

An EmailMesssage subclass with improved header and message ID support.

This class knows about several headers (standard and variations), including Sender/X-Sender, In-Reply-To/References`, and Reply-To.

The generated Message-ID header from the e-mail can be accessed via the message_id attribute after the e-mail has been sent.

In order to prevent issues when sending on behalf of users whose e-mail domains are controlled by DMARC, callers can specify from_spoofing (or set settings.DJBLETS_EMAIL_FROM_SPOOFING). When set, the e-mail address used for the From header will only be used if there aren’t any DMARC rules that may prevent the e-mail from being sent/received.

Note

Releases prior to Djblets 1.0.10 required using enable_smart_spoofing or settings.EMAIL_ENABLE_SMART_SPOOFING, which didn’t allow From spoofing to be completely disabled.)

In the event that a DMARC rule would prevent sending on behalf of that user, the sender address will be used instead, with the full name appearing as the value in from_email with “via <Service Name>” tacked onto it.

Callers wishing to use this should also set settings.EMAIL_DEFAULT_SENDER_SERVICE_NAME to the desired service name. Otherwise, the domain on the sender e-mail will be used instead.

This class also supports repeated headers.

Changed in version 1.0.10: Added the from_spoofing parameter and settings.DJBLETS_EMAIL_FROM_SPOOFING to replace enable_smart_spoofing and settings.EMAIL_ENABLE_SMART_SPOOFING.

FROM_SPOOFING_ALWAYS = 'always'¶

Always spoof the From address for a user.

FROM_SPOOFING_SMART = 'smart'¶

Only spoof the From address for a user if allowed by DMARC rules.

FROM_SPOOFING_NEVER = 'never'¶

Never spoof the From address for a user.

__init__(subject='', text_body='', html_body='', from_email=None, to=None, cc=None, bcc=None, sender=None, in_reply_to=None, headers=None, auto_generated=False, prevent_auto_responses=False, from_spoofing=None, enable_smart_spoofing=None)¶

Create a new EmailMessage.

Parameters:

• subject (unicode, optional) – The subject of the message. Defaults to being blank (which MTAs might replace with “no subject”.)

• text_body (unicode, optional) – The body of the e-mail as plain text. Defaults to an empty string (allowing HTML-only e-mails to be sent).

• html_body (unicode, optional) – The body of the e-mail as HTML. Defaults to an empty string (allowing text-only e-mails to be sent).

• from_email (unicode, optional) – The from address for the e-mail. Defaults to DEFAULT_FROM_EMAIL.

• to (list, optional) – A list of e-mail addresses as unicode objects that are to receive the e-mail. Defaults to an empty list of addresses (allowing using CC/BCC only).

• cc (list, optional) – A list of e-mail addresses as unicode objects that are to receive a carbon copy of the e-mail, or None if there are no CC recipients.

• bcc (list, optional) – A list of e-mail addresses as unicode objects that are to receive a blind carbon copy of the e-mail, or None if there are not BCC recipients.

• sender (unicode, optional) –

  The actual e-mail address sending this e-mail, for use in the Sender header. If this differs from from_email, it will be left out of the header as per RFC 2822.

  This will default to DEFAULT_FROM_EMAIL if unspecified.

• in_reply_to (unicode, optional) – An optional message ID (which will be used as the value for the In-Reply-To and References headers). This will be generated if not provided and will be available as the message_id attribute after the e-mail has been sent.

• headers (django.utils.datastructures.MultiValueDict, optional) – Extra headers to provide with the e-mail.

• auto_generated (bool, optional) – If True, the e-mail will contain headers that mark it as an auto-generated message (as per RFC 3834) to avoid auto replies.

• prevent_auto_responses (bool, optional) – If True, the e-mail will contain headers to prevent auto replies for delivery reports, read receipts, out of office e-mails, and other auto-generated e-mails from Exchange.

• from_spoofing (int, optional) –

  Whether to spoof the From header for the user. This can be one of FROM_SPOOFING_ALWAYS, FROM_SPOOFING_SMART, or FROM_SPOOFING_NEVER.

  This defaults to None, in which case the enable_smart_spoofing will be checked (for legacy reasons), falling back to settings.DJBLETS_EMAIL_FROM_SPOOFING (which defaults to FROM_SPOOFING_ALWAYS, also for legacy reasons).

• enable_smart_spoofing (bool, optional) –

  Whether to enable smart spoofing of any e-mail addresses for the From header (if from_spoofing is None). This defaults to settings.EMAIL_ENABLE_SMART_SPOOFING.

  This is deprecated in favor of from_spoofing.

message()¶

Construct an outgoing message for the e-mail.

This will construct a message based on the data provided to the constructor. This represents the e-mail that will later be sent using send().

After calling this method, the message’s ID will be stored in the message_id attribute for later reference.

This does not need to be called manually. It’s called by send().

Returns:

The resulting message.

Return type:

django.core.mail.message.SafeMIMEText

recipients()¶

Return a list of all recipients of the e-mail.

Returns:

A list of all recipients included on the To, CC, and BCC lists.

Return type:

list