Partager via

Fonctionnalité d’envoi des compléments Outlook

  • Article

La fonctionnalité d’envoi pour les compléments Outlook permet de gérer un message ou un élément de réunion, ou de bloquer les utilisateurs de certaines actions, et permet à un complément de définir certaines propriétés lors de l’envoi.

Remarque

La fonctionnalité d’envoi n’est pas prise en charge dans les compléments qui utilisent le manifeste unifié pour Microsoft 365. Obtenez des effets similaires en utilisant l’activation basée sur les événements et en implémentant un gestionnaire pour les événements OnMessageSend ou OnAppointmentSend , ou les deux. Consultez également la note ci-dessous sur les alertes intelligentes.

Par exemple, utilisez la fonctionnalité d’envoi pour :

  • Empêcher un utilisateur d’envoyer des informations sensibles ou de laisser la ligne d’objet vide.
  • Ajouter un destinataire spécifique à la ligne CC dans les messages ou à la ligne destinataires facultatifs des réunions.

La fonctionnalité d’envoi est déclenchée par le type d’événement ItemSend et est sans interface utilisateur.

Pour en savoir plus sur les limites de la fonctionnalité d’envoi, consultez la section Limites plus loin dans cet article.

Remarque

Les alertes intelligentes sont une version plus récente de la fonctionnalité d’envoi. Il a été publié dans l’ensemble de conditions requises 1.12 et a introduit les OnMessageSend événements et OnAppointmentSend . À l’instar de la fonctionnalité d’envoi, les alertes intelligentes permettent à votre complément de case activée que certaines conditions sont remplies avant l’envoi d’un élément de courrier. Les alertes intelligentes se différencient de la fonctionnalité d’envoi comme suit :

Pour plus d’informations sur les différences entre les alertes intelligentes et la fonctionnalité d’envoi, consultez Différences entre les alertes intelligentes et la fonctionnalité d’envoi. Nous vous invitons à tester les alertes intelligentes en suivant la procédure pas à pas.

Clients et plateformes pris en charge

Le tableau suivant présente les combinaisons client-serveur prises en charge pour la fonctionnalité d’envoi, y compris la mise à jour cumulative minimale requise le cas échéant. Les combinaisons exclues ne sont pas prises en charge.

Client Exchange Online Exchange 2019 en local
(Mise à jour cumulative 1 ou ultérieure)		 Exchange 2016 en local
(Mise à jour cumulative 6 ou ultérieure)
Navigateur Web
interface utilisateur Outlook moderne

nouvel Outlook sur Windows		 Oui Non applicable Non applicable
Navigateur Web
interface utilisateur Outlook classique		 Non applicable Oui Oui
Windows (classique)
Version 1910 (build 12130.20272) ou ultérieure		 Oui Oui Oui
Mac
Version 16.47 (21031401) ou ultérieure		 Oui Oui Oui

Remarque

La fonctionnalité d’envoi a été officiellement publiée dans l’ensemble de conditions requises 1.8 (pour plus d’informations, consultez prise en charge actuelle du serveur et du client ). Toutefois, notez que la matrice de prise en charge de la fonctionnalité est un sur-ensemble de l’ensemble de conditions requises.

Importante

Les compléments qui utilisent la fonctionnalité d’envoi ne sont pas autorisés dans AppSource.

Comment marche la fonctionnalité d’envoi ?

Vous pouvez utiliser la fonctionnalité d’envoi pour créer un complément Outlook qui intègre l’événement synchrone ItemSend. Cet événement détecte le moment où l’utilisateur clique sur le bouton Envoyer(ou le bouton Envoyer mise à jour pour les réunions existantes) et peut servir à bloquer l’envoi de l’élément s’il n’est pas validé. Par exemple, quand un utilisateur déclenche un événement d’envoi de message, un complément Outlook qui utilise la fonctionnalité d’envoi peut :

  • Lisez et validez le contenu du message électronique.
  • Vérifiez que le message inclut une ligne d’objet.
  • Définissez un destinataire prédéterminé.

La validation est effectuée côté client dans Outlook lorsque l’événement d’envoi est déclenché et que le complément a jusqu’à 5 minutes avant son expiration. Si la validation échoue, l’envoi de l’élément est bloqué et un message d’erreur s’affiche dans une barre d’informations qui invite l’utilisateur à prendre des mesures.

Remarque

Dans Outlook sur le web et la nouvelle version d’Outlook sur Windows, lorsque la fonctionnalité d’envoi est déclenchée dans un message composé dans l’onglet du navigateur Outlook, l’élément est affiché dans sa propre fenêtre ou onglet de navigateur afin d’effectuer la validation et d’autres traitements.

La capture d’écran suivante montre une barre d’informations invitant l’expéditeur à renseigner l’objet du message.

Message d’erreur invitant l’utilisateur à entrer une ligne d’objet manquante.

La capture d’écran suivante montre une barre d’informations informant l’expéditeur que des mots bloqués ont été trouvés.

Message d’erreur indiquant à l’utilisateur que des mots bloqués ont été trouvés.

Limites

Les limites de la fonctionnalité d’envoi sont les suivantes.

  • Fonctionnalité Append-on-send : si vous appelez item.body.AppendOnSendAsync dans le gestionnaire lors de l’envoi, une erreur est retournée.

  • AppSource : vous ne pouvez pas publier de compléments Outlook qui utilisent la fonctionnalité d’envoi à AppSource , car ils échouent à la validation AppSource. Les compléments qui utilisent la fonctionnalité d’envoi doivent être déployés par les administrateurs. Si vous souhaitez que l’option de publier votre complément sur AppSource, envisagez d’utiliser des alertes intelligentes à la place, qui est une version plus récente de la fonctionnalité d’envoi. Pour en savoir plus sur les alertes intelligentes et sur le déploiement de ces compléments, voir Utiliser les alertes intelligentes et les événements OnMessageSend et OnAppointmentSend dans votre complément Outlook et les options de liste AppSource pour votre complément Outlook basé sur les événements.

    Importante

    Lorsque vous exécutez npm run validate pour valider le manifeste de votre complément, vous recevez l’erreur « Le complément de boîte aux lettres contenant l’événement ItemSend n’est pas valide. Le manifeste du complément de boîte aux lettres contient l’événement ItemSend dans VersionOverrides, ce qui n’est pas autorisé. » Ce message s’affiche car les compléments qui utilisent l’événement ItemSend , requis pour cette version de la fonctionnalité d’envoi, ne peuvent pas être publiés sur AppSource. Vous pourrez toujours charger une version test et exécuter votre complément, à condition qu’aucune autre erreur de validation n’ait été trouvée.

  • Manifeste : un ItemSend seul événement est pris en charge par complément. Si votre manifeste comprend plusieurs événements ItemSend, il ne sera pas validé.

  • Performances : plusieurs allers-retours vers le serveur web qui héberge le complément peuvent affecter les performances du complément. Tenez compte des effets sur les performances lorsque vous créez des compléments qui nécessitent plusieurs opérations basées sur des messages ou des réunions.

  • Envoyer plus tard (Mac uniquement) : s’il existe des compléments lors de l’envoi, la fonctionnalité Envoyer plus tard n’est pas disponible.

En outre, il n’est pas recommandé d’appeler item.close() dans le gestionnaire d’événements lors de l’envoi, car la fermeture de l’élément doit se produire automatiquement une fois l’événement terminé.

Limites concernant le type ou le mode de boîte aux lettres

La fonctionnalité d’envoi est prise en charge uniquement pour les boîtes aux lettres utilisateur dans Outlook sur le web, Windows (nouveau et classique) et Mac. En plus des situations où les compléments ne s’activent pas comme indiqué dans la section Éléments de boîte aux lettres disponibles pour les compléments de la page de vue d’ensemble des compléments Outlook, la fonctionnalité n’est actuellement pas prise en charge pour le mode hors connexion où ce mode est disponible.

Dans les cas où les compléments Outlook ne s’activent pas, le complément lors de l’envoi ne s’exécute pas et le message est envoyé.

Toutefois, si la fonctionnalité d’envoi est activée et disponible, mais que le scénario de boîte aux lettres n’est pas pris en charge, Outlook n’autorise pas l’envoi.

Compléments d’envoi multiples

Si plusieurs compléments d’envoi sont installés, ils s’exécutent dans l’ordre dans lequel ils sont reçus par les API getAppManifestCall ou getExtensibilityContext. Si le premier complément autorise l’envoi du message, le deuxième complément peut modifier un paramètre qui le bloque. Par contre, le premier complément n’est pas réexécuté si les autres compléments installés autorisent l’envoi.

Par exemple, Complément1 et Complément2 utilisent la fonctionnalité d’envoi. Complément1 est installé en premier, et Complément2 en deuxième. Complément1 vérifie que le mot Fabrikam apparaît dans le message pour autoriser l’envoi. À l’inverse, Complément2 supprime toutes les occurrences du mot Fabrikam. Le message est alors envoyé sans le mot Fabrikam (à cause de l’ordre d’installation de Complément1 et Complément2).

Déployer des compléments Outlook qui utilisent la fonctionnalité d’envoi

Nous recommandons aux administrateurs de déployer les compléments Outlook qui utilisent la fonctionnalité d’envoi. Les administrateurs doivent vérifier que le complément d’envoi :

  • est présent lors de l’ouverture d’un élément de composition (pour les e-mails : nouveau message, répondre ou transférer).
  • ne peut pas être fermé ou désactivé par l’utilisateur.

Installer des compléments Outlook qui utilisent la fonctionnalité d’envoi

Dans Outlook, la fonctionnalité d’envoi exige la configuration des compléments en fonction des types d’événement d’envoi. Sélectionnez la plateforme que vous voulez configurer.

Les compléments pour les Outlook sur le web (modernes) et les nouveaux Outlook sur Windows qui utilisent la fonctionnalité d’envoi doivent s’exécuter pour tous les utilisateurs qui les ont installés. Toutefois, si les utilisateurs doivent exécuter des compléments lors de l’envoi pour répondre aux normes de conformité, l’indicateur OnSendAddinsEnabled doit être défini true sur la stratégie de boîte aux lettres afin que la modification de l’élément ne soit pas autorisée pendant le traitement des compléments lors de l’envoi.

Pour installer un nouveau complément, exécutez les cmdlets Exchange Online PowerShell suivantes.

$Data=Get-Content -Path '.\Contoso Message Body Checker.xml' -Encoding Byte –ReadCount 0

New-App -OrganizationApp -FileData $Data -DefaultStateForUser Enabled

Remarque

Pour découvrir comment utiliser PowerShell à distance afin de se connecter à Exchange Online, consultez la rubrique Connexion à Exchange Online PowerShell.

Activer l’indicateur d’envoi

Les administrateurs peuvent appliquer la conformité lors de l’envoi en exécutant Exchange Online applets de commande PowerShell.

Pour tous les utilisateurs, pour interdire la modification pendant le traitement des compléments lors de l’envoi :

  1. Créez une stratégie de boîte aux lettres.

     New-OWAMailboxPolicy OWAOnSendAddinAllUserPolicy

    Remarque

    Les administrateurs peuvent utiliser une stratégie existante, mais la fonctionnalité d’envoi est uniquement prise en charge sur certains types de boîtes aux lettres. Les boîtes aux lettres non prises en charge ne peuvent pas envoyer par défaut dans Outlook sur le web et outlook sur Windows.

  2. Appliquer la conformité lors de l’envoi.

     Get-OWAMailboxPolicy OWAOnSendAddinAllUserPolicy | Set-OWAMailboxPolicy –OnSendAddinsEnabled:$true

  3. Attribuez la stratégie à des utilisateurs.

     Get-User -Filter {RecipientTypeDetails -eq 'UserMailbox'}|Set-CASMailbox -OwaMailboxPolicy OWAOnSendAddinAllUserPolicy

Activer l’indicateur d’envoi pour un groupe d’utilisateurs

Pour appliquer la conformité à l’envoi pour un groupe spécifique d’utilisateurs, les étapes sont les suivantes. Dans cet exemple, un administrateur souhaite uniquement activer une stratégie de complément d’envoi dans un environnement pour les utilisateurs Finance (où les utilisateurs Finance se trouvent dans le service Finance).

  1. Créez une stratégie de boîte aux lettres pour le groupe.

     New-OWAMailboxPolicy FinanceOWAPolicy

    Remarque

    Les administrateurs peuvent utiliser une stratégie existante, mais la fonctionnalité d’envoi est uniquement prise en charge sur certains types de boîtes aux lettres (pour en savoir plus, consultez la section Limites concernant le type de boîte aux lettres plus haut dans cet article). Les boîtes aux lettres non prises en charge ne peuvent pas envoyer par défaut dans Outlook sur le web et outlook sur Windows.

  2. Appliquer la conformité lors de l’envoi.

     Get-OWAMailboxPolicy FinanceOWAPolicy | Set-OWAMailboxPolicy –OnSendAddinsEnabled:$true

  3. Attribuez la stratégie à des utilisateurs.

     $targetUsers = Get-Group 'Finance'|select -ExpandProperty members
 $targetUsers | Get-User -Filter {RecipientTypeDetails -eq 'UserMailbox'}|Set-CASMailbox -OwaMailboxPolicy FinanceOWAPolicy

Remarque

vous devez attendre 60 minutes avant que la stratégie prenne effet. Sinon, redémarrez Internet Information Services (IIS). Lorsque la stratégie prend effet, la conformité à l’envoi est appliquée pour le groupe.

Désactiver l’indicateur d’envoi

Pour désactiver l’application de conformité lors de l’envoi pour un utilisateur, affectez une stratégie de boîte aux lettres pour laquelle l’indicateur n’est pas activé en exécutant les applets de commande suivantes. Dans cet exemple, la stratégie de boîte aux lettres est ContosoCorpOWAPolicy.

Get-CASMailbox joe@contoso.com | Set-CASMailbox –OWAMailboxPolicy "ContosoCorpOWAPolicy"

Remarque

Pour plus d’informations sur l’utilisation de l’applet de commande Set-OwaMailboxPolicy pour configurer des Outlook sur le web existantes ou de nouvelles stratégies de boîte aux lettres Outlook sur Windows, voir Set-OwaMailboxPolicy.

Pour désactiver l’application de la conformité lors de l’envoi pour tous les utilisateurs auxquels une stratégie de boîte aux lettres Outlook sur Windows ou un Outlook sur le web spécifique est affectée, exécutez les applets de commande suivantes.

Get-OWAMailboxPolicy OWAOnSendAddinAllUserPolicy | Set-OWAMailboxPolicy –OnSendAddinsEnabled:$false

Scénarios de la fonctionnalité d’envoi

Voici tous les scénarios pris en charge et non pour les compléments qui utilisent la fonctionnalité d’envoi.

Les gestionnaires d’événements sont définis dynamiquement

Les gestionnaires d’événements de votre complément doivent être définis à l’heure Office.initialize ou Office.onReady() sont appelés (pour plus d’informations, voir Démarrage d’un complément Outlook et Initialiser votre complément Office). Si votre code de gestionnaire est défini dynamiquement par certaines circonstances lors de l’initialisation, vous devez créer une fonction stub pour appeler le gestionnaire une fois qu’il est complètement défini. La fonction stub doit être référencée dans l’attribut de FunctionName l’élément <Event> de votre manifeste. Cette solution de contournement garantit que votre gestionnaire est défini et prêt à être référencé une fois Office.initialize ou s’exécute Office.onReady() .

Si votre gestionnaire n’est pas défini une fois votre complément initialisé, l’expéditeur reçoit une notification indiquant que « La fonction de rappel est inaccessible » via une barre d’informations dans l’élément de courrier.

La fonctionnalité d’envoi est activée sur la boîte aux lettres de l’utilisateur, mais aucun complément n’est installé.

Dans ce scénario, l’utilisateur peut envoyer des messages et des éléments de réunion sans qu’aucun complément ne s’exécute.

La fonctionnalité d’envoi est activée sur la boîte aux lettres de l’utilisateur et les compléments qui prennent en charge cette fonctionnalité sont installés et activés

Les compléments s’exécutent pendant l’événement d’envoi pour autoriser ou empêcher l’utilisateur d’envoyer son message.

Délégation de boîte aux lettres, où la Boîte aux lettres 1 dispose des autorisations d’accès total à la Boîte aux lettres 2

Navigateur web (Outlook classique)

Scénario Fonctionnalité d’envoi (Boîte aux lettres 1) Fonctionnalité d’envoi (Boîte aux lettres 2) Session web Outlook (classique) Résultat Pris en charge ?
1 Activé Activé Nouvelle session La boîte aux lettres 1 ne peut pas envoyer un message ou un élément de réunion provenant de la boîte aux lettres 2. N’est pas pris en charge actuellement. Pour contourner ce problème, utilisez le scénario 3.
2 Désactivé Activé Nouvelle session La boîte aux lettres 1 ne peut pas envoyer un message ou un élément de réunion provenant de la boîte aux lettres 2. N’est pas pris en charge actuellement. Pour contourner ce problème, utilisez le scénario 3.
3 Activé Activé Même session Les compléments d’envoi attribués à la boîte aux lettres 1 exécutent la fonctionnalité d’envoi. Pris en charge.
4 Activé Désactivé Nouvelle session Aucun complément d’envoi ne s’exécute ; un message ou un élément de réunion est envoyé. Pris en charge.

Navigateur web (Outlook moderne), Windows, Mac

Pour appliquer l’envoi, les administrateurs doivent s’assurer que la stratégie a été activée sur les deux boîtes aux lettres. Pour savoir comment prendre en charge l’accès délégué dans un complément, consultez Activer les scénarios de boîte aux lettres partagées et de dossiers partagés.

La fonctionnalité/stratégie d’envoi est activée sur la boîte aux lettres de l’utilisateur, les compléments qui prennent en charge cette fonctionnalité sont installés et activés et le mode hors connexion est activé

Les compléments d’envoi s’exécutent en fonction de l’état en ligne de l’utilisateur, du serveur principal du complément et d’Exchange.

État de l’utilisateur

Les compléments d’envoi s’exécutent pendant l’envoi, si l’utilisateur est en ligne. Si l’utilisateur est hors ligne, les compléments d’envoi ne s’exécutent pas pendant l’envoi et l’élément message ou réunion n’est pas envoyé.

État du serveur de complément

Un complément sur envoi s’exécute si son serveur principal est en ligne et joignable. Si le serveur principal est hors connexion, l’envoi est désactivé.

État d’Exchange

Les compléments d’envoi s’exécutent pendant l’envoi, si le serveur Exchange est en ligne et joignable. Si le complément sur envoi ne peut pas accéder à Exchange et que la stratégie ou l’applet de commande applicable sont activés, l’envoi est désactivé.

Remarque

Sur Mac en mode hors connexion, le bouton Envoyer (ou le bouton Envoyer mise à jour pour les réunions existantes) est désactivé et une notification indique que l’organisation n’autorise pas l’envoi lorsque l’utilisateur est hors connexion.

L’utilisateur peut modifier l’élément pendant que les compléments d’envoi y travaillent

Pendant que les compléments lors de l’envoi traitent un élément, l’utilisateur peut modifier l’élément en ajoutant, par exemple, du texte ou des pièces jointes inappropriés. Si vous souhaitez empêcher l’utilisateur de modifier l’élément pendant le traitement de votre complément lors de l’envoi, vous pouvez implémenter une solution de contournement à l’aide d’une boîte de dialogue. Cette solution de contournement peut être utilisée dans Outlook sur le web (classique), Windows (classique) et Mac.

Importante

Outlook sur le web moderne et nouvel Outlook sur Windows : pour empêcher l’utilisateur de modifier l’élément pendant le traitement de votre complément lors de l’envoi, vous devez définir l’indicateur OnSendAddinsEnabled sur comme décrit dans la section Installer les compléments Outlook qui utilisent l’envoi plus haut dans cet article.true

Dans votre gestionnaire d’envoi :

  1. Appelez displayDialogAsync pour ouvrir une boîte de dialogue afin que les clics de souris et les séquences de touches soient désactivés.

    Importante

    Pour obtenir ce comportement dans les Outlook sur le web classiques, vous devez définir la propriété truedisplayInIframe sur dans le options paramètre de l’appeldisplayDialogAsync.

  2. Implémenter le traitement de l’élément.

  3. Fermez la boîte de dialogue. Gérez également ce qui se passe si l’utilisateur ferme la boîte de dialogue.

Exemples de code

Les exemples de code ci-dessous vous montrent comment créer un complément d’envoi simple. Pour télécharger l’exemple de code sur lequel se basent ces exemples, consultez l’article Outlook-Add-in-On-Send.

Conseil

Si vous utilisez un dialogue avec l’événement on-send, veillez à fermer le dialogue avant de terminer l’événement.

Manifeste, remplacement de version et événement

L’exemple de code Outlook-Add-in-On-Send comprend deux manifestes :

  • Contoso Message Body Checker.xml: montre comment case activée le corps d’un message pour les mots restreints ou les informations sensibles lors de l’envoi.

  • Contoso Subject and CC Checker.xml : montre comment ajouter un destinataire à la ligne CC et vérifier que le message inclut une ligne d’objet lors de l’envoi.

Dans le fichier manifeste Contoso Message Body Checker.xml, insérez le fichier de fonction et le nom de la fonction qui doit être appelée lors d’un événement ItemSend. L’opération s’exécute de façon synchrone.

<Hosts>
    <Host xsi:type="MailHost">
        <DesktopFormFactor>
            <!-- The functionfile and function name to call on message send.  -->
            <!-- In this case, the function validateBody will be called within the JavaScript code referenced in residUILessFunctionFileUrl. -->
            <FunctionFile resid="residUILessFunctionFileUrl" />
            <ExtensionPoint xsi:type="Events">
                <Event Type="ItemSend" FunctionExecution="synchronous" FunctionName="validateBody" />
            </ExtensionPoint>
        </DesktopFormFactor>
    </Host>
</Hosts>

Importante

Si vous utilisez Visual Studio 2019 pour développer votre complément lors de l’envoi, vous pouvez recevoir un avertissement de validation comme suit : « Il s’agit d’un xsi :type 'http://schemas.microsoft.com/office/mailappversionoverrides/1.1:Events'non valide ». Pour contourner ce problème, vous aurez besoin d’une version plus récente du MailAppVersionOverridesV1_1.xsd, qui a été fournie en tant que gist GitHub dans un blog sur cet avertissement.

Pour le fichier manifeste Contoso Subject and CC Checker.xml, l’exemple suivant montre le fichier de fonction et le nom de la fonction à appeler dans l’événement d’envoi du message.

<Hosts>
    <Host xsi:type="MailHost">
        <DesktopFormFactor>
            <!-- The functionfile and function name to call on message send.  -->
            <!-- In this case the function validateSubjectAndCC will be called within the JavaScript code referenced in residUILessFunctionFileUrl. -->
            <FunctionFile resid="residUILessFunctionFileUrl" />
            <ExtensionPoint xsi:type="Events">
                <Event Type="ItemSend" FunctionExecution="synchronous" FunctionName="validateSubjectAndCC" />
            </ExtensionPoint>
        </DesktopFormFactor>
    </Host>
</Hosts>

L’API d’envoi nécessite VersionOverrides v1_1. L’exemple vous montre comment ajouter le nœud VersionOverrides dans votre manifeste.

 <VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides" xsi:type="VersionOverridesV1_0">
     <!-- On-send requires VersionOverridesV1_1 -->
     <VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides/1.1" xsi:type="VersionOverridesV1_1">
         ...
     </VersionOverrides>
</VersionOverrides>

Remarque

Pour en savoir plus sur les manifestes pour les compléments Outlook, voir Manifeste des compléments Office.

Les objets Event et item et les méthodes body.getAsync et body.setAsync

Pour accéder au message ou élément de réunion sélectionné (dans cet exemple, le message que vous venez de composer), utilisez l’espace de noms Office.context.mailbox.item. L’événement ItemSend est automatiquement passé par la fonctionnalité d’envoi à la fonction spécifiée dans le manifeste, dans cet exemple, la validateBody fonction .

let mailboxItem;

Office.initialize = function (reason) {
    mailboxItem = Office.context.mailbox.item;
}

// Entry point for Contoso Message Body Checker add-in before send is allowed.
// <param name="event">ItemSend event is automatically passed by on-send code to the function specified in the manifest.</param>
function validateBody(event) {
    mailboxItem.body.getAsync("html", { asyncContext: event }, checkBodyOnlyOnSendCallBack);
}

La validateBody fonction obtient le corps actuel au format spécifié (HTML) et transmet l’objet ItemSend d’événement auquel le code souhaite accéder dans la fonction de rappel. En plus de la méthode getAsync, l’objet Body fournit également une méthode setAsync utile pour remplacer le corps du message par le texte spécifié.

Remarque

Pour en savoir plus, consultez les articles relatifs à l’objet Event et à la méthode Body.getAsync.

Objet NotificationMessages et méthode event.completed

La fonction checkBodyOnlyOnSendCallBack utilise une expression régulière pour déterminer si le corps du message contient des mots bloqués. Si elle trouve une correspondance dans un tableau de mots bloqués, il bloque l’envoi du message et avertit l’expéditeur via la barre d’informations. Pour ce faire, il utilise la notificationMessages propriété de l’objet Item pour renvoyer un objet NotificationMessages . Il ajoute ensuite une notification à l’élément en appelant la méthode addAsync, comme illustré dans l’exemple suivant.

// Determine whether the body contains a specific set of blocked words. If it contains the blocked words, block email from being sent. Otherwise allow sending.
// <param name="asyncResult">ItemSend event passed from the calling function.</param>
function checkBodyOnlyOnSendCallBack(asyncResult) {
    const listOfBlockedWords = new Array("blockedword", "blockedword1", "blockedword2");
    const wordExpression = listOfBlockedWords.join('|');

    // \b to perform a "whole words only" search using a regular expression in the form of \bword\b.
    // i to perform case-insensitive search.
    const regexCheck = new RegExp('\\b(' + wordExpression + ')\\b', 'i');
    const checkBody = regexCheck.test(asyncResult.value);

    if (checkBody) {
        mailboxItem.notificationMessages.addAsync('NoSend', { type: 'errorMessage', message: 'Blocked words have been found in the body of this email. Please remove them.' });
        // Block send.
        asyncResult.asyncContext.completed({ allowEvent: false });
    }

    // Allow send.
    asyncResult.asyncContext.completed({ allowEvent: true });
}

Voici les paramètres de la addAsync méthode .

  • NoSend : chaîne qui est une clé spécifiée par le développeur pour référencer un message de notification. Vous pouvez l’utiliser pour modifier ce message ultérieurement. La clé ne peut pas comporter plus de 32 caractères.
  • type : une des propriétés du paramètre d’objet JSON. Représente le type d’un message ; les types correspondent aux valeurs de l’énumération Office.MailboxEnums.ItemNotificationMessageType. Les valeurs possibles sont Indicateur de progression, Message d’information ou Message d’erreur. Dans cet exemple, type est un message d’erreur.
  • message : une des propriétés du paramètre d’objet JSON. Dans cet exemple, message correspond au texte du message de notification.

Pour signaler que le complément a terminé le traitement de l’événement ItemSend déclenché par l’opération d’envoi, appelez la méthode event.completed({allowEvent :Boolean}). La propriété allowEvent est une valeur booléenne. Si la valeur est définie sur true, l’envoi est autorisé. Si la valeur est définie sur false, l’envoi du message est bloqué.

Méthodes replaceAsync, removeAsync et getAllAsync

En plus de la méthode addAsync, l'objet NotificationMessages inclut également les méthodes replaceAsync, removeAsync et getAllAsync. Ces méthodes ne sont pas utilisées dans cet exemple de code. Pour plus d’informations, consultez l’article relatif à l’objet NotificationMessages.

Code vérificateur de l’objet et de la ligne CC

L’exemple de code suivant vous montre comment ajouter un destinataire à la ligne Cc et vérifier que le message comporte un objet pendant l’envoi. Cet exemple utilise la fonctionnalité d’envoi pour autoriser ou interdire l’envoi d’un e-mail.

// Invoke by Contoso Subject and CC Checker add-in before send is allowed.
// <param name="event">ItemSend event is automatically passed by on-send code to the function specified in the manifest.</param>
function validateSubjectAndCC(event) {
    shouldChangeSubjectOnSend(event);
}

// Determine whether the subject should be changed. If it is already changed, allow send. Otherwise change it.
// <param name="event">ItemSend event passed from the calling function.</param>
function shouldChangeSubjectOnSend(event) {
    mailboxItem.subject.getAsync(
        { asyncContext: event },
        function (asyncResult) {
            addCCOnSend(asyncResult.asyncContext);
            //console.log(asyncResult.value);
            // Match string.
            const checkSubject = (new RegExp(/\[Checked\]/)).test(asyncResult.value)
            // Add [Checked]: to subject line.
            subject = '[Checked]: ' + asyncResult.value;

            // Determine whether a string is blank, null, or undefined.
            // If yes, block send and display information bar to notify sender to add a subject.
            if (asyncResult.value === null || (/^\s*$/).test(asyncResult.value)) {
                mailboxItem.notificationMessages.addAsync('NoSend', { type: 'errorMessage', message: 'Please enter a subject for this email.' });
                asyncResult.asyncContext.completed({ allowEvent: false });
            }
            else {
                // If can't find a [Checked]: string match in subject, call subjectOnSendChange function.
                if (!checkSubject) {
                    subjectOnSendChange(subject, asyncResult.asyncContext);
                    //console.log(checkSubject);
                }
                else {
                    // Allow send.
                    asyncResult.asyncContext.completed({ allowEvent: true });
                }
            }
        });
}

// Add a CC to the email. In this example, CC contoso@contoso.onmicrosoft.com
// <param name="event">ItemSend event passed from calling function</param>
function addCCOnSend(event) {
    mailboxItem.cc.setAsync(['Contoso@contoso.onmicrosoft.com'], { asyncContext: event });
}

// Determine whether the subject should be changed. If it is already changed, allow send, otherwise change it.
// <param name="subject">Subject to set.</param>
// <param name="event">ItemSend event passed from the calling function.</param>
function subjectOnSendChange(subject, event) {
    mailboxItem.subject.setAsync(
        subject,
        { asyncContext: event },
        function (asyncResult) {
            if (asyncResult.status == Office.AsyncResultStatus.Failed) {
                mailboxItem.notificationMessages.addAsync('NoSend', { type: 'errorMessage', message: 'Unable to set the subject.' });

                // Block send.
                asyncResult.asyncContext.completed({ allowEvent: false });
            }
            else {
                // Allow send.
                asyncResult.asyncContext.completed({ allowEvent: true });
            }
        });
}

Pour savoir comment ajouter un destinataire à la ligne Cc et vérifier que le message comporte une ligne d’objet pendant l’envoi, et découvrir les API disponibles, consultez l’article relatif à l’exemple Outlook-Add-in-On-Send. Le code est accompagné de commentaires détaillés.

Déboguer des compléments Outlook qui utilisent l’envoi

Pour obtenir des instructions sur le débogage de votre complément lors de l’envoi, voir Debug function commands in Outlook add-ins.

Conseil

Si l’erreur « La fonction de rappel est inaccessible » s’affiche lorsque vos utilisateurs exécutent votre complément et que le gestionnaire d’événements de votre complément est défini dynamiquement, vous devez créer une fonction stub comme solution de contournement. Pour plus d’informations, consultez Les gestionnaires d’événements sont définis dynamiquement .

Voir aussi