E-mails¶
Like SMS E-mail messages are stored inside Django model class and sent via backend. Again we provide more e-mail backends, every backend uses different e-mail service like Mandrill, AWS SNS or standard SMTP. For sending e-mail message you can use function pymess.backend.email.send
or pymwess.backend.email.send_template
.
-
pymess.backend.emails.
send
(sender, recipient, subject, content, sender_name=None, related_objects=None, attachments=None, tag=None, **email_kwargs)¶ Parameter
sender
define source e-mail address of the message, you can specify the name of the sender with optional parametersender_name
.recipient
is destination e-mail address. Subject and HTML content of the e-mail message is defined withsubject
andcontent
parameters. Attributerelated_objects
should contain a list of objects that you want to connect with the send message (with generic relation). Optional parameterattachments
should contains list of files that will be sent with the e-mail in format({file name}, {output stream with file content}, {content type})
.tag
is string mark which is stored with the sent SMS message . The last non required parameter**email_kwargs
is extra data that will be stored inside e-mail message model in fieldextra_data
.
-
pymess.backend.emails.
send_template
(recipient, slug, context_data, related_objects=None, attachments=None, tag=None)¶ The second function is used for sending prepared templates that are stored inside template model (class that extends
pymess.models.sms.AbstractEmailTemplate
). The first parameterrecipient
is e-mail address of the receiver,slug
is key of the template,context_data
is a dictionary that contains context data for rendering e-mail content from the template,related_objects
should contains list of objects that you want to connect with the send message,attachments
should contains list of files that will be send with the e-mail andtag
is string mark which is stored with the sent SMS message.
Models¶
-
class
pymess.models.emails.
EmailMessage
¶ The model contains data of already sent e-mail messages.
-
created_at
¶ Django
DateTimeField
, contains date and time of creation.
-
changed_at
¶ Django
DateTimeField
, contains date and time the of last change.
-
sent_at
¶ Django
DateTimeField
, contains date and time of sending the e-mail message.
-
recipient
¶ EmailField
that contains e-mail address of the receiver.
-
sender
¶ EmailField
that contains e-mail address of th sender.
-
sender_name
¶ CharField
that contains readable/friendly sender name.
-
subject
¶ TextField
, contains subject of the e-mail message.
-
content
¶ TextField
, contains content of the e-mail message.
-
template_slug
¶ If e-mail was sent from the template, this attribute cointains key of the template.
-
template
¶ If e-mail was sent from the template, this attribute contains foreign key of the template. The reason why there is
template_slug
andtemplate
fields is that a template instance can be removed and it is good to keep at least the key of the template.
-
state
¶ Contains the current state of the message. Allowed states are:
- WAITING - e-mail was not sent to the external service
- SENDING - e-mail was sent to the external service
- SENT - e-mail was sent to the receiver
- ERROR - error was raised during sending of the e-mail message
- DEBUG - e-mail was not sent because system is in debug mode
-
backend
¶ Field contains path to the e-mail backend that was used for sending of the SMS message.
-
error
¶ If error was raised during sending of the SMS message this field contains text description of the error.
-
extra_data
¶ Extra data stored with
JSONField
.
-
extra_sender_data
¶ Extra data related to the e-mail backend stored with
JSONField
. Every SMS backend can have different extra data.
-
tag
¶ String tag that you can define during sending SMS message.
-
failed
¶ Returns
True
if SMS ended inERROR
state.
Returns DB manager of
pymess.models.emails.EmailRelatedObject
model that are related to the concrete e-mail message.
-
-
class
pymess.models.emails.
EmailRelatedObject
¶ Model for storing related objects that you can connect with the e-mail message.
-
created_at
¶ Django
DateTimeField
, contains date and time of creation.
-
changed_at
¶ Django
DateTimeField
, contains date and time the of last change.
-
email_message
¶ Foreign key to the e-mail message.
-
content_type
¶ Content type of the stored model (generic relation)
-
object_id_int
¶ If a related objects have primary key in integer format the key is stored here. This field uses db index, therefore filtering is much faster.
-
object_id
¶ Primary key of a related object stored in django
TextField
.
-
-
class
pymess.models.emails.
Attachment
¶ Django model that contains e-mail attachments.
-
created_at
¶ Django
DateTimeField
, contains date and time of creation.
-
changed_at
¶ Django
DateTimeField
, contains date and time the of last change.
-
email_message
¶ Foreign key to the e-mail message.
-
content_type
¶ Django
CharField
, contains content type of the attachment.
-
file
¶ Django
FileField
, contains file which was send to the recipient.
-
-
class
pymess.models.emails.
AbstractEmailTemplate
¶ Abstract class of e-mail template which you can use to define your own e-mail template model. Your model that extends this class is set inside setting
PYMESS_EMAIL_TEMPLATE_MODEL
:PYMESS_EMAIL_TEMPLATE_MODEL = 'your_application.YourEmailTemplateModel'
-
created_at
¶ Django
DateTimeField
, contains date and time of creation.
-
changed_at
¶ Django
DateTimeField
, contains date and time the of last change.
-
slug
¶ Key of the e-mail template in the string format (Django slug).
-
sender
¶ EmailField
that contains e-mail address of the sender.
-
sender_name
¶ CharField
that contains readable/friendly sender name.
-
subject
¶ TextField
, contains subject of the e-mail message. Final e-mail subject is rendered with Django template system by default.
-
body
¶ Body of the e-mail message. Final e-mail content is rendered with Django template system by default.
-
get_body
()¶ Returns body of the model message. You can use it to update e-mail body before rendering.
-
render_body
(context_data)¶ Renders template stored inside
body
field to the message content. Standard Django template system is used by default.
-
get_subject
()¶ Returns subject of the model message. You can use it to update e-mail subject before rendering.
-
render_subject
(context_data)¶ Renders template stored inside
subject
field to the message content. Standard Django template system is used by default.
-
can_send
(recipient, context_data)¶ Returns by default
True
value. If you need to restrict sending e-mail template for some reasons, you can override this method.
-
send
(recipient, context_data, related_objects=None, tag=None, attachments=None)¶ Checks if message can be sent, renders message content and sends it via defined backend. Finally, the sent message is returned. If message cannot be sent,
None
is returned.
-
-
class
pymess.models.emails.
EmailTemplate
¶ Default template model class that only inherits from
pymess.models.emails.AbstractEmailTemplate
Backends¶
Backend is a class that is used for sending messages. Every backend must provide API defined by pymess.backends.emails.EmailBackend
class. E-mail backend is configured via PYMESS_EMAIL_SENDER_BACKEND
(ex. PYMESS_EMAIL_SENDER_BACKEND = 'pymess.backend.emails.smtp.SMTPEmailBackend'
). There are currently implemented following e-mail backends:
-
class
pymess.backend.emails.dummy.
DummyEmailBackend
¶ Backend that can be used for testing. E-mail is not sent, but is automatically set to the
DEBUG
state.
-
class
pymess.backend.emails.smtp.
SMTPEmailBackend
¶ Backend that uses standard SMTP service for sending e-mails. Configuration of SMTP is same as Django configuration.
-
class
pymess.backend.emails.mandrill.
MandrillEmailBackend
¶ Backend that uses mandrill service for sending e-mail messages (https://mandrillapp.com/api/docs/index.python.html). For this purpose you must have installed
mandrill
library.Configuration of attributes according to Mandrill operator documentation (the names of the configuration are the same):
PYMESS_EMAIL_MANDRILL_CONFIG = { 'KEY': '', # Mandrill notification key 'HEADERS': None, 'TRACK_OPENS': False, 'TRACK_CLICKS': False, 'AUTO_TEXT': False, 'INLINE_CSS': False, 'URL_STRIP_QS': False, 'PRESERVE_RECIPIENTS': False, 'VIEW_CONTENT_LINK': True, 'ASYNC': False, }
Custom backend¶
If you want to write your own Pymess e-mail backend, you must create class that inherits from pymess.backends.emails.EmailBackend
:
.. class pymess.backends.sms.EmailBackend
publish_message
(message)¶This method should send e-mail message (obtained from the input argument) and update its state. This method must be overridden in the custom backend.
Commands¶
send_emails_batch
¶
As mentioned e-mails can be sent in a batch with Django command send_emails_batch
.
sync_emails
¶
Store e-mail body in a HTML file is better from code readability. Therefore this command updates e-mails body from HTML files store in directory. You can select the directory with command property directory
or you can set directory with setting PYMESS_EMAIL_HTML_DATA_DIRECTORY
. E-mails body in the directory is stored like HTML file named with e-mail slug and html as a suffix.
dump_emails
¶
E-mail body can be changed in the database therefore reverse operation to sync_emails
can be done with this command. You must select directory where e-mails body in HTML format will be stored.