For ESPs that support receiving inbound email, Anymail offers normalized handling of inbound events.
Once you’ve enabled webhooks, Anymail will send a
custom Django signal for each ESP inbound message it receives.
You can connect your own receiver function to this signal for further processing.
(This is very much like how Anymail handles status tracking
events for sent messages. Inbound events just use a different signal receiver
and have different event parameters.)
Be sure to read Django’s listening to signals docs for information on defining and connecting signal receivers.
from anymail.signals import inbound from django.dispatch import receiver @receiver(inbound) # add weak=False if inside some other function/class def handle_inbound(sender, event, esp_name, **kwargs): message = event.message print("Received message from %s (envelope sender %s) with subject '%s'" % ( message.from_email, message.envelope_sender, message.subject))
Some ESPs batch up multiple inbound messages into a single webhook call. Anymail will invoke your signal receiver once, separately, for each message in the batch.
Be careful with inbound email
Inbound email is user-supplied content. There are all kinds of ways a malicious sender can abuse the email format to give your app misleading or dangerous data. Treat inbound email content with the same suspicion you’d apply to any user-submitted data. Among other concerns:
Senders can spoof the From header. An inbound message’s
from_emailmay or may not match the actual address that sent the message. (There are both legitimate and malicious uses for this capability.)
Most other fields in email can be falsified. E.g., an inbound message’s
datemay or may not accurately reflect when the message was sent.
Inbound attachments have the same security concerns as user-uploaded files. If you process inbound attachments, you’ll need to verify that the attachment content is valid.
This is particularly important if you publish the attachment content through your app. For example, an “image” attachment could actually contain an executable file or raw HTML. You wouldn’t want to serve that as a user’s avatar.
It’s not sufficient to check the attachment’s content-type or filename extension—senders can falsify both of those. Consider using python-magic or a similar approach to validate the actual attachment content.
The Django docs have additional notes on user-supplied content security.
Normalized inbound event¶
eventparameter to Anymail’s
inboundsignal receiver is an object with the following attributes:
stridentifying the type of event. For inbound events, this is always
This is typically when the ESP received the message or shortly thereafter. (Use
event.message.dateif you’re interested in when the message was sent.)
(The timestamp’s timezone is often UTC, but the exact behavior depends on your ESP and account settings. Anymail ensures that this value is an aware datetime with an accurate timezone.)
strunique identifier for the event, if available; otherwise
None. Can be used to avoid processing the same event twice. The exact format varies by ESP, and very few ESPs provide an event_id for inbound messages.
An alternative approach to avoiding duplicate processing is to use the inbound message’s Message-ID header (
The “raw” event data from the ESP, deserialized into a python data structure. For most ESPs this is either parsed JSON (as a
dict), or sometimes the complete Django
HttpRequestreceived by the webhook.
This gives you (non-portable) access to original event provided by your ESP, which can be helpful if you need to access data Anymail doesn’t normalize.
Normalized inbound message¶
messageattribute of an
AnymailInboundEventis an AnymailInboundMessage—an extension of Python’s standard
email.message.Messagewith additional features to simplify inbound handling.
In addition to the base
Messagefunctionality, it includes these attributes:
The actual sending address of the inbound message, as determined by your ESP. This is a
str“addr-spec”—just the email address portion without any display name (
Noneif the ESP didn’t provide a value.
The envelope sender often won’t match the message’s From header—for example, messages sent on someone’s behalf (mailing lists, invitations) or when a spammer deliberately falsifies the From address.
The actual destination address the inbound message was delivered to. This is a
str“addr-spec”—just the email address portion without any display name (
Noneif the ESP didn’t provide a value.
The envelope recipient may not appear in the To or Cc recipient lists—for example, if your inbound address is bcc’d on a message.
The value of the message’s From header. Anymail converts this to an
EmailAddressobject, which makes it easier to access the parsed address fields:
>>> str(message.from_email) # the fully-formatted address '"Dr. Justin Customer, CPA" <email@example.com>' >>> message.from_email.addr_spec # the "email" portion of the address 'firstname.lastname@example.org' >>> 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'
(This API is borrowed from Python 3.6’s
envelope_recipientif you need to know the actual inbound address that received the inbound message.
The value of the message’s Date header, as a
Noneif the Date header is missing or invalid. This attribute will almost always be an aware datetime (with a timezone); in rare cases it can be naive if the sending mailer indicated that it had no timezone information available.
The Date header is the sender’s claim about when it sent the message, which isn’t necessarily accurate. (If you need to know when the message was received at your ESP, that might be available in
event.timestamp. If not, you’d need to parse the messages’s Received headers, which can be non-trivial.)
dictmapping inline Content-ID references to attachment content. Each key is an “unquoted” cid without angle brackets. E.g., if the
<img src="cid:abc123...">, you could get that inline image using
The content of each attachment is described in Handling Inbound Attachments below.
floatspam score (usually from SpamAssassin) if your ESP provides it; otherwise
None. The range of values varies by ESP and spam-filtering configuration, so you may need to experiment to find a useful threshold.
If your ESP provides a simple yes/no spam determination, a
boolindicating whether the ESP thinks the inbound message is probably spam. Otherwise
None. (Most ESPs just assign a
spam_scoreand leave its interpretation up to you.)
If provided by your ESP, a simplified version the inbound message’s plaintext body; otherwise
What exactly gets “stripped” varies by ESP, but it often omits quoted replies and sometimes signature blocks. (And ESPs who do offer stripped bodies usually consider the feature experimental.)
Other headers, complex messages, etc.
message['reply-to'] # the Reply-To header (header keys are case-insensitive) message.getall('DKIM-Signature') # list of all DKIM-Signature headers
Handling Inbound Attachments¶
Anymail converts each inbound attachment to a specialized MIME object with additional methods for handling attachments and integrating with Django.
The attachment objects in an AnymailInboundMessage’s
attachments list and
have these methods:
# allow users to mail in jpeg attachments to set their profile avatars... if attachment.get_content_type() == "image/jpeg": # for security, you must verify the content is really a jpeg # (you'll need to supply the is_valid_jpeg function) if is_valid_jpeg(attachment.get_content_bytes()): user.profile.avatar_image = attachment.as_uploaded_file()
See Django’s docs on Managing files for more information on working with uploaded files.
The type of attachment content, as specified by the sender. (But remember attachments are essentially user-uploaded content, so you should never trust the sender.)
(Note that you cannot determine the attachment type using code like
issubclass(attachment, email.mime.image.MIMEImage). You should instead use something like
attachment.get_content_maintype() == 'image'. The email package’s specialized MIME subclasses are designed for constructing new messages, and aren’t used for parsing existing, inbound email messages.)
The original filename of the attachment, as specified by the sender.
Never use this filename directly to write files—that would be a huge security hole. (What would your app do if the sender gave the filename “/etc/passwd” or “../settings.py”?)
Returns the lowercased value (without parameters) of the attachment’s Content-Disposition header. The return value should be either “inline” or “attachment”, or
Noneif the attachment is somehow missing that header.
Returns the content of the attachment decoded to Unicode text. (This is generally only appropriate for text or message-type attachments.)
If provided, charset will override the attachment’s declared charset. (This can be useful if you know the attachment’s Content-Type has a missing or incorrect charset.)
The errors param is as in
decode(). The default “replace” substitutes the Unicode “replacement character” for any illegal characters in the text.
Returns the raw content of the attachment as bytes. (This will automatically decode any base64-encoded attachment data.)
An Anymail inbound attachment is actually just an
AnymailInboundMessageinstance, following the Python email package’s usual recursive representation of MIME messages. All
email.message.Messagefunctionality is available on attachment objects (though of course not all features are meaningful in all contexts).
This can be helpful for, e.g., parsing email messages that are forwarded as attachments to an inbound message.
Anymail loads all attachment content into memory as it processes each inbound
message. This may limit the size of attachments your app can handle, beyond
any attachment size limits imposed by your ESP. Depending on how your ESP transmits
attachments, you may also need to adjust Django’s
setting to successfully receive larger attachments.
Inbound signal receiver functions¶
Your Anymail inbound signal receiver must be a function with this signature:
def my_handler(sender, event, esp_name, **kwargs):
(You can name it anything you want.)
sender (class) – The source of the event. (One of the
anymail.webhook.*View classes, but you generally won’t examine this parameter; it’s required by Django’s signal mechanism.)
esp_name (str) – e.g., “SendMail” or “Postmark”. If you are working with multiple ESPs, you can use this to distinguish ESP-specific handling in your shared event processing.
**kwargs – Required by Django’s signal mechanism (to support future extensions).
any exceptions in your signal receiver will result in a 400 HTTP error to the webhook. See discussion below.
If (any of) your signal receivers raise an exception, Anymail will discontinue processing the current batch of events and return an HTTP 400 error to the ESP. Most ESPs respond to this by re-sending the event(s) later, a limited number of times.
This is the desired behavior for transient problems (e.g., your Django database being unavailable), but can cause confusion in other error cases. You may want to catch some (or all) exceptions in your signal receiver, log the problem for later follow up, and allow Anymail to return the normal 200 success response to your ESP.
Some ESPs impose strict time limits on webhooks, and will consider them failed if they don’t respond within (say) five seconds. And they may then retry sending these “failed” events, which could cause duplicate processing in your code. If your signal receiver code might be slow, you should instead queue the event for later, asynchronous processing (e.g., using something like celery).
If your signal receiver function is defined within some other
function or instance method, you must use the
option when connecting it. Otherwise, it might seem to work at first,
but will unpredictably stop being called at some point—typically
on your production server, in a hard-to-debug way. See Django’s
docs on signals for more information.