Le module Mailer permet d'envoyer des documents Mayan par e-mail, sous forme de pièce jointe ou de lien. Il supporte plusieurs profils de messagerie (SMTP, fichier), des gabarits de message configurables, et s'intègre dans les workflows pour l'envoi automatique.
UserMailer) — Configuration d'un serveur d'envoi (SMTP, etc.) avec label, activé/désactivé, défautClasse : DjangoSMTP
| Champ | Type | Défaut | Description |
|---|---|---|---|
host |
CharField | localhost |
Hostname du serveur SMTP |
port |
IntegerField | 25 |
Port SMTP |
use_tls |
BooleanField | False |
TLS explicite (STARTTLS, port 587) |
use_ssl |
BooleanField | False |
TLS implicite (SSL, port 465) |
username |
CharField | — | Identifiant SMTP |
password |
CharField | — | Mot de passe SMTP |
from |
CharField | — | Adresse expéditeur |
use_tlsetuse_sslsont mutuellement exclusifs. Utiliseruse_tls(port 587) pour la plupart des serveurs modernes.
Classe : DjangoFileBased
Écrit les e-mails dans des fichiers .eml dans un répertoire local, sans les envoyer. Utile pour tester la configuration des gabarits.
| Champ | Description |
|---|---|
file_path |
Répertoire de destination des fichiers .eml |
from |
Adresse expéditeur (cosmétique) |
Gmail / Google Workspace :
Host: smtp.gmail.com
Port: 587
Use TLS: ✓ (STARTTLS)
Use SSL: ✗
Username: votre-compte@gmail.com
Password: [mot de passe d'application Google]
From: votre-compte@gmail.com
Exchange / Office 365 :
Host: smtp.office365.com
Port: 587
Use TLS: ✓
Username: votre-compte@domaine.com
Password: votre-mot-de-passe
From: votre-compte@domaine.com
Serveur SMTP interne (sans auth) :
Host: smtp.interne.local
Port: 25
Use TLS: ✗
Use SSL: ✗
From: mayan@interne.local
Une fois le profil créé :
# Via le shell Django
from mayan.apps.mailer.models import UserMailer
profile = UserMailer.objects.get(label='SMTP Production')
profile.test(to='test@example.com', user=None)
# Vérifier les erreurs éventuelles
for err in profile.error_log.all():
print(err.text)
Envoyer un document (lien) :
Envoyer un fichier en pièce jointe :
Envoi multiple :
Dans la liste de documents, sélectionner plusieurs documents puis Actions → Envoyer par e-mail.
| Objet | Lien | Pièce jointe |
|---|---|---|
| Document | ✓ | ✗ |
| DocumentFile | ✓ | ✓ |
| DocumentVersion | ✓ | ✓ |
L'envoi en pièce jointe exporte le document/fichier/version dans un format portable avant de l'attacher à l'e-mail.
# Envoyer un document par lien
curl -X POST \
-H "Authorization: Token <token>" \
-H "Content-Type: application/json" \
-d '{
"mailing_profile": 1,
"recipient": "destinataire@example.com",
"subject": "Document partagé",
"body": "Voici le lien vers le document."
}' \
"https://mayan.example.com/api/v4/objects/documents/document/42/mailing/link/"
# Envoyer un fichier en pièce jointe
curl -X POST \
-H "Authorization: Token <token>" \
-H "Content-Type: application/json" \
-d '{
"mailing_profile": 1,
"recipient": "destinataire@example.com",
"subject": "Fichier en pièce jointe",
"body": "Veuillez trouver le document en pièce jointe."
}' \
"https://mayan.example.com/api/v4/objects/documents/documentfile/7/mailing/attachment/"
from mayan.apps.mailer.models import UserMailer
from mayan.apps.documents.models import Document
profile = UserMailer.objects.get(label='SMTP Production')
doc = Document.objects.get(pk=42)
profile.send_object(
obj=doc,
to='destinataire@example.com',
subject='Document important',
body='<p>Bonjour, veuillez trouver ci-joint le document.</p>',
as_attachment=False, # True pour pièce jointe
cc='copie@example.com', # optionnel
bcc='bcc@example.com', # optionnel
reply_to='reply@example.com', # optionnel
user=None
)
Les sujets et corps des e-mails utilisent des gabarits Django Template avec des variables contextuelles.
| Variable | Description | Exemple |
|---|---|---|
{{ object }} |
Représentation textuelle du document | Facture_2024-001.pdf |
{{ object_name }} |
Nom du modèle | Document |
{{ link }} |
URL complète vers l'objet (envoi par lien uniquement) | https://mayan.example.com/documents/42/ |
| Type d'envoi | Paramètre | Valeur par défaut |
|---|---|---|
| Pièce jointe — sujet | MAILER_DOCUMENT_SUBJECT_TEMPLATE |
{{ object_name }}: {{ object }} |
| Pièce jointe — corps | MAILER_DOCUMENT_BODY_TEMPLATE |
Attached to this email is the {{ object_name }}: {{ object }} |
| Lien — sujet | MAILER_LINK_SUBJECT_TEMPLATE |
Link for {{ object_name }}: {{ object }} |
| Lien — corps | MAILER_LINK_BODY_TEMPLATE |
To access this {{ object_name }} click on the following link: {{ link }} |
Administration → Paramètres → Mailer → modifier les 4 gabarits.
Ou via variable d'environnement :
MAYAN_MAILER_LINK_SUBJECT_TEMPLATE="[Mayan] {{ object_name }} partagé : {{ object }}"
MAYAN_MAILER_LINK_BODY_TEMPLATE="Bonjour,\n\nVeuillez cliquer sur ce lien pour accéder au {{ object_name }} :\n{{ link }}\n\n---\nCe message a été envoyé automatiquement."
Le corps supporte le HTML. Le sujet est toujours converti en texte brut (balises HTML supprimées).
Séparer les adresses par virgule ou point-virgule :
destinataire1@example.com, destinataire2@example.com; copie@example.com
Le mailer s'intègre dans les workflows pour envoyer automatiquement des e-mails lors de transitions.
Dans un état de workflow :
| Champ | Description | Gabarit Django |
|---|---|---|
| Profil de messagerie | Quel profil utiliser | Non |
| Destinataire | Adresse(s) email | Oui |
| CC | Copie | Oui |
| BCC | Copie cachée | Oui |
| Reply-To | Répondre à | Oui |
| Sujet | Sujet de l'e-mail | Oui |
| Corps | Corps de l'e-mail | Oui |
| Pièce jointe | Attacher le document | Non (case à cocher) |
Les champs Destinataire, CC, BCC, Sujet, Corps acceptent la syntaxe Django Template avec accès aux variables du workflow :
{# Destinataire dynamique depuis les métadonnées du document #}
{{ document.metadata.email_destinataire }}
{# Sujet avec le label du document #}
Approbation requise : {{ document.label }}
{# Corps avec informations du workflow #}
Le document "{{ document.label }}" a été soumis le {{ document.datetime_created|date:"d/m/Y" }}.
Veuillez l'examiner : {{ link }}
Scénario : Lorsqu'un document passe en état "En attente d'approbation", envoyer un e-mail au responsable.
Action type : Send document via email
Profil : SMTP Production
Destinataire : responsable@example.com
Sujet : [Approbation] {{ document.label }}
Corps : Le document "{{ document.label }}" nécessite votre approbation.
Accéder au document : {{ link }}
Pièce jointe : ✗
Queue : mailing
Worker : worker_c (nice=10, concurrence=4)
L'envoi est toujours asynchrone — la tâche est mise en queue et le formulaire retourne immédiatement. Le statut d'envoi est visible dans le journal d'erreurs du profil de messagerie.
Tâche : task_send_object
Paramètres : content_type_id, object_id, mailing_profile_id, recipient, subject, body, as_attachment, user_id, etc.
Profils de messagerie :
| Méthode | URL | Permission | Description |
|---|---|---|---|
GET |
/api/v4/mailing_profiles/ |
mailing_profile_view |
Lister les profils |
POST |
/api/v4/mailing_profiles/ |
mailing_profile_create |
Créer un profil |
GET |
/api/v4/mailing_profiles/{id}/ |
mailing_profile_view |
Détail d'un profil |
PATCH |
/api/v4/mailing_profiles/{id}/ |
mailing_profile_edit |
Modifier un profil |
DELETE |
/api/v4/mailing_profiles/{id}/ |
mailing_profile_delete |
Supprimer un profil |
Envoi :
| Méthode | URL | Permission | Description |
|---|---|---|---|
POST |
/api/v4/objects/documents/document/{id}/mailing/link/ |
send_document_link |
Envoyer lien document |
POST |
/api/v4/objects/documents/documentfile/{id}/mailing/attachment/ |
send_document_file_attachment |
Envoyer fichier en PJ |
POST |
/api/v4/objects/documents/documentfile/{id}/mailing/link/ |
send_document_file_link |
Envoyer lien fichier |
POST |
/api/v4/objects/documents/documentversion/{id}/mailing/attachment/ |
send_document_version_attachment |
Envoyer version en PJ |
POST |
/api/v4/objects/documents/documentversion/{id}/mailing/link/ |
send_document_version_link |
Envoyer lien version |
| Permission | Description |
|---|---|
mailing_profile_create |
Créer des profils de messagerie |
mailing_profile_delete |
Supprimer des profils |
mailing_profile_edit |
Modifier des profils |
mailing_profile_use |
Utiliser un profil pour envoyer |
mailing_profile_view |
Voir les profils |
send_document_link |
Envoyer un lien vers un document |
send_document_file_attachment |
Envoyer un fichier en pièce jointe |
send_document_file_link |
Envoyer un lien vers un fichier |
send_document_version_attachment |
Envoyer une version en pièce jointe |
send_document_version_link |
Envoyer un lien vers une version |
| Événement | Quand |
|---|---|
event_email_sent |
E-mail envoyé avec succès |
event_mailing_profile_created |
Profil de messagerie créé |
event_mailing_profile_edited |
Profil de messagerie modifié |
docker compose logs worker_c | grep -i mailSMTPAuthenticationError: 535 Authentication failed
ConnectionRefusedError: [Errno 111] Connection refused
telnet smtp.example.com 587Les pièces jointes sont générées dynamiquement (export du document). Pour les documents volumineux, préférer l'envoi par lien.
Certains serveurs SMTP limitent la taille des messages. Configurer la limite côté serveur ou utiliser un backend dédié aux gros fichiers.
| Fichier | Rôle |
|---|---|
models.py |
UserMailer — modèle de profil |
mailers.py |
DjangoSMTP, DjangoFileBased — backends |
classes.py |
MailerBackend — classe de base |
workflow_actions.py |
DocumentEmailAction — action de workflow |
tasks.py |
task_send_object — tâche Celery |
queues.py |
Configuration de la queue mailing |
settings.py |
Gabarits et paramètres globaux |
permissions.py |
Définition des permissions |
events.py |
Définition des événements |
serializers.py |
MailingProfileSerializer, MailingProfileActionSerializer |