Français
  • A propos du composant BSPK
  • ATL
  • BWEB
  • Historique des versions
  • FAQ

    • La classe Mail

    cs.bspkComponent.Mail envoie un e-mail par SMTP, Microsoft 365 ou Gmail. Le serveur est lu dans les fichiers de paramètres, le corps peut venir d'un modèle HTML, les pièces jointes sont gérées, et les destinataires sont automatiquement redirigés sur les machines de développement et de préproduction.

    Envoyer un mail

    var $Mail : cs.bspkComponent.Mail
var $vo_Status : Object

$Mail:=cs.bspkComponent.Mail.new("Votre commande"; ""; $vt_Email)  // sujet ; message ; destinataire
$Mail.setMessageFromTpl("commandeConfirmee.html"; {prenom: $User.firstName; reference: $Order.ref})
$Mail.addAttachements($vt_CheminPdf; "Facture.pdf")
$vo_Status:=$Mail.send()
If ($vo_Status=Null) || (Not(Bool($vo_Status.success)))
	// non envoyé
End if

    Les trois paramètres du constructeur sont facultatifs.

    Configurer

    La classe lit Storage.vo_Param, c'est-à-dire les fichiers de paramètres :

    CléRôle
    vo_Mail.vt_Host, vl_Port, vt_User, vt_PasswordLe serveur SMTP.
    vo_Mail.vt_ForwarderL'expéditeur par défaut.
    vo_Mail.vb_AcceptUnsecureConnectionAccepter une connexion non chiffrée.
    vo_MS365OAuth2 : vt_ClientId (obligatoire), vt_ClientSecret, vt_Tenant (common), vt_Permission (service), vt_Scope, vt_RedirectURI, vt_UserIdEnvoi par Microsoft 365 (Graph, via 4D NetKit). En mode service sans secret client, la classe revient au SMTP. La boîte d'envoi est vt_UserId, à défaut l'expéditeur.
    vo_GoogleOAuth2 : clientId (obligatoire), clientSecret, redirectURI, scope (gmail.send), accessType (offline), name, permission (signedIn) — sans préfixe vt_Envoi par Gmail. Demande un jeton déjà obtenu et stocké : l'autorisation Google n'est pas fournie par le composant.
    vt_RedirectMail, vo_RedirectMappingLa redirection, ci-dessous.

    setServer($host; $port; $user; $password), setOAuth2($obj) et setOAuth2Google($obj) remplacent cette configuration pour une instance.

    Renseignez toujours vo_Mail. Sans lui, la classe se rabat sur des réglages par défaut qui ne sont pas ceux de votre application.

    Les fonctions

    FonctionCe qu'elle fait
    setSubject($texte)Remplace le sujet. En mode DEV, le préfixe [DEV] est ajouté.
    setMessage($texte)Le même texte en corps texte et en corps HTML.
    setMessageFromTpl($chemin; $params; $langue)Le corps HTML depuis un modèle, ci-dessous.
    setRecipient($adresse)Remplace le destinataire. Les espaces sont retirés ; l'adresse doit être valide (plusieurs adresses séparées par , ou ;).
    setRecipients($collection)Ajoute des destinataires.
    setCC($texteOuCollection), setBcc(…)Ajoutent des copies ; une adresse invalide est ignorée sans message.
    setReplyTo($adresse)Ignorée si l'adresse est invalide.
    setFrom($adresse)Vide ou invalide : vo_Mail.vt_Forwarder.
    addAttachements($doc; $nom; $cid; $type; $disposition)Orthographié Attachements. Un texte est le chemin d'un document existant (ignoré sinon). $cid et "inline" pour une image affichée dans le HTML.
    setLogFile($chemin)Le fichier doit déjà exister.
    send() → ObjectGmail si configuré, sinon Microsoft 365 si configuré, sinon SMTP. Renvoie le statut (success, status, statusText). Renvoie Null s'il manque un élément obligatoire : serveur, sujet, corps, destinataire ou expéditeur.

    Les modèles

    setMessageFromTpl("commandeConfirmee"; $params; "fr") :

    • .html est ajouté si le nom n'a pas d'extension .html ou .htm, et le chemin est cherché sous Mail/ dans le dossier web de votre projet (en général BWEB/Mail/commandeConfirmee.html).
    • Le modèle passe par PROCESS 4D TAGS : dans le modèle, l'objet de paramètres est $1 (<!--#4DTEXT $1.prenom--> : Indéfinie).
    • La langue ("fr") remplace celle du process le temps du traitement, pour les traductions du modèle — seulement si une langue est déjà posée, c'est-à-dire dans une requête web. Dans un worker ou une tâche planifiée, elle est ignorée.

    Modèle introuvable : le corps est vide, sans erreur, et l'envoi réussit quand même. Vérifiez le chemin.

    La redirection en développement et en préproduction

    En mode DEV ou PREPROD seulement (voir Les fichiers de paramètres), setRecipient et setRecipients envoient à :

    1. vo_RedirectMapping[<nom de la machine>], une adresse par poste ; sinon
    2. vt_RedirectMail, s'il n'est pas vide ; sinon
    3. personne d'autre : le vrai destinataire.

    Le sujet devient alors [REDIRECTION DEV MODE][<destinataire d'origine>] ….

    • Les copies (setCC, setBcc) ne sont jamais redirigées. Sur une machine de développement qui travaille sur des données réelles, une copie à un client part chez le client.
    • Appelez setSubject avant setRecipient : setSubject remplace le sujet et efface la mention de redirection. Le constructeur les appelle dans le bon ordre.

    Quand l'envoi échoue

    Par SMTP ou Microsoft 365, un échec déclenche un rapport d'erreur envoyé à l'adresse des mails d'erreur. Par Gmail, aucun rapport : lisez le statut renvoyé.

    Bon à savoir

    • Avec Microsoft 365, une pièce jointe doit être un chemin (texte), un BLOB ou une image : un objet 4D.File est ignoré.
    • BSPK_EMAIL_Validate_Addresses($texte) renvoie vrai si chaque adresse (séparées par , ou ;) est valide. Un texte vide renvoie vrai.

    Voir aussi