Jump to >

djblets.mail.message

E-mail message composition and sending.

class EmailMessage(subject=u'', text_body=u'', html_body=u'', 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)[source]

Bases: django.core.mail.message.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 = u'always'[source]

Always spoof the From address for a user.

FROM_SPOOFING_SMART = u'smart'[source]

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

FROM_SPOOFING_NEVER = u'never'[source]

Never spoof the From address for a user.

__init__(subject=u'', text_body=u'', html_body=u'', 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)[source]

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()[source]

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()[source]

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