django-anymail

MailerSend supports two personalization syntaxes. Anymail only supports the advanced personalization syntax.

If your MailerSend templates use the simple syntax ({$variable_name}), you must convert them to the advanced syntax ({{ variable_name }}) to work with Anymail's merge_data and merge_global_data.

Anymail emulates global merge data by copying merge_global_data values to every recipient, as MailerSend does not natively support global merge data.

message = EmailMessage(
    from_email="shipping@example.com",
    subject="Your order {{ order_no }} has shipped",
    body="""Hi {{ name }},\n                We shipped your order {{ order_no }}\n                on {{ ship_date }}.""",
    to=["alice@example.com", "Bob <bob@example.com>"]
)
message.merge_data = {
    "alice@example.com": {"name": "Alice", "order_no": "12345"},
    "bob@example.com": {"name": "Bob", "order_no": "54321"},
}
message.merge_global_data = {
    "ship_date": "May 15"
}
message.esp_extra = {
    "batch-send-mode": "use-bulk-email"
}

You can attach metadata to messages for later retrieval (e.g., via Anymail's status tracking webhooks).

• metadata: A dict of metadata values applied to the entire message.
• merge_metadata: A dict of per-recipient metadata values. The keys are recipient email addresses (address portion only), and the values are dictionaries of metadata.

Best Practices & Warnings:

• Portability: Use alphanumeric keys and string/numeric values.
• Security: Some ESPs expose this metadata in email headers. Do not include sensitive data.
• Precedence: If keys conflict, merge_metadata values take precedence over metadata for a specific recipient.

# Global metadata
message.metadata = {"customer": customer.id, "order": order.reference_number}

# Per-recipient metadata
message.to = ["wile@example.com", "Mr. Runner <rr@example.com>"]
message.merge_metadata = {
    "wile@example.com": {"customer": 123, "order": "acme-zxyw"},
    "rr@example.com": {"customer": 45678, "order": "acme-wblt"},
}

The anymail.inbound.AnymailInboundMessage class is an extension of Python's standard email.message.EmailMessage. It is provided as the .message attribute of an AnymailInboundEvent to simplify handling inbound emails. It includes enhanced attributes for accessing envelope information, parsed email addresses, and content like HTML, plaintext, and attachments.

Key features include:

• Envelope Information: Access envelope_sender and envelope_recipient to see the actual routing addresses, which may differ from the From or To headers.
• Parsed Addresses: The from_email attribute is converted to an anymail.utils.EmailAddress object, allowing easy access to addr_spec, display_name, domain, and username.
• Content Access: Provides direct access to text (plaintext), html, attachments, and inlines (inline images).
• Spam Metadata: Includes spam_score and spam_detected if provided by your ESP.
• Compatibility: Since it inherits from EmailMessage, you can use all standard Python email methods like .walk(), .get_content_type(), and header mapping.

>>> str(message.from_email)  # the fully-formatted address
'"Dr. Justin Customer, CPA" <jcustomer@example.com>'
>>> message.from_email.addr_spec  # the "email" portion of the address
'jcustomer@example.com'
>>> message.from_email.display_name  # empty string if no display name
'Dr. Justin Customer, CPA'
>>> message.from_email.domain
'example.com'
>>> message.from_email.username
'jcustomer'

If your ESP supports it, you can use merge_headers to provide unique email headers for each recipient in a multi-recipient message.

When merge_headers is used, Anymail utilizes the ESP's batch sending option, ensuring each recipient receives an individual message and cannot see other recipients in the to list.

• Keys: The keys in the merge_headers dictionary must be the recipient email addresses (address portion only).
• Values: A dictionary of header fields and values for that recipient.
• Defaults: If a header is defined in message.extra_headers but not in merge_headers, it will be applied to all recipients. If a header is defined in merge_headers for only some recipients, behavior for the others depends on the ESP (some include an empty header, others omit it).

message.to = ["wile@example.com", "R. Runner <rr@example.com>"]
message.extra_headers = {
    # Headers for all recipients
    "List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
}
message.merge_headers = {
    # Per-recipient headers
    "wile@example.com": {
        "List-Unsubscribe": "<https://example.com/unsubscribe/12345>",
    },
    "rr@example.com": {
        "List-Unsubscribe": "<https://example.com/unsubscribe/98765>",
    },
}