djblets.mail.message¶

E-mail message composition and sending.

class EmailMessage(*, subject: str = '', text_body: str = '', html_body: str = '', from_email: Optional[str] = None, to: Optional[Sequence[str]] = None, cc: Optional[Sequence[str]] = None, bcc: Optional[Sequence[str]] = None, sender: Optional[str] = None, in_reply_to: Optional[str] = None, headers: Optional[Union[Dict[str, str], MultiValueDict[str, str]]] = None, auto_generated: bool = False, prevent_auto_responses: bool = False, from_spoofing: Optional[str] = None, enable_smart_spoofing: Optional[bool] = None, reply_to: Optional[Sequence[str]] = None)[source]¶

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'[source]¶

Always spoof the From address for a user.

FROM_SPOOFING_SMART = 'smart'[source]¶

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

FROM_SPOOFING_NEVER = 'never'[source]¶

Never spoof the From address for a user.

__init__(*, subject: str = '', text_body: str = '', html_body: str = '', from_email: Optional[str] = None, to: Optional[Sequence[str]] = None, cc: Optional[Sequence[str]] = None, bcc: Optional[Sequence[str]] = None, sender: Optional[str] = None, in_reply_to: Optional[str] = None, headers: Optional[Union[Dict[str, str], MultiValueDict[str, str]]] = None, auto_generated: bool = False, prevent_auto_responses: bool = False, from_spoofing: Optional[str] = None, enable_smart_spoofing: Optional[bool] = None, reply_to: Optional[Sequence[str]] = None) → None[source]¶

Create a new EmailMessage.

Parameters:

• subject (str, optional) –

  The subject of the message.

  Defaults to being blank (which MTAs might replace with “no subject”.)

• text_body (str, 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 (str, optional) –

  The body of the e-mail as HTML.

  Defaults to an empty string (allowing text-only e-mails to be sent).

• from_email (str, optional) –

  The from address for the e-mail.

  Defaults to DEFAULT_FROM_EMAIL.

• to (list, optional) –

  A list of e-mail addresses 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 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 that are to receive a blind carbon copy of the e-mail, or None if there are not BCC recipients.

• sender (str, 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 (str, 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 (str, optional) –

  Optional behavior for spoofing a user’s e-mail address in the From header.

  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.

  Deprecated since version 4.0: This will be removed in Djblets 6.

• reply_to (str, optional) –

  An explicit user used for the Reply-To header.

  If not provided, this defaults to from_email (if provided).

  New in version 4.0.

message_id: Optional[str]¶

The stored Message-ID of the sent e-mail.

__annotations__ = {'_headers': 'MultiValueDict[str, str]', 'message_id': 'Optional[str]'}¶

message() → SafeMIMEText[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