MAPSNDMAIL/en

<languages />
==Introduction== 


With Opale and the MAPSNDMAIL command, you can now send e-mails that have PDF documents attached to them and a customised HTML body.


The '''MAPSNDMAIL''' command uses a Designer template as a parameter ("Mapping format" parameter). The template has to be generated in PDF.
It has to include INDEX zones used as dynamic data in the subject, attachment name, or in the e-mail body.

== Generality on the MAPSNDMAIL command== 
==Prior to V10.1==

The MAPSNDMAIL command on IBM i uses multiple parameters:


Spooled file . . . . . . . . . .                 Name                                   <span style="color:blue">Nom du spool</span>
 Spooled file number  . . . . . .   *LAST         *LAST *ONLY   000000-999999            <span style="color:blue">Numéro du spool</span>
 Job Name . . . . . . . . . . . .   *CURRENT      Name, *CURRENT , *DEV                  <span style="color:blue">Nom du job</span>
 Job number . . . . . . . . . . .                 000000-999999                          <span style="color:blue">Numéro du job</span>
 User . . . . . . . . . . . . . .   *CURRENT      Name                                   <span style="color:blue">User</span>
 Mapping format . . . . . . . . .                 Character value,10 max.                <span style="color:blue">Format M-Designer</span>
 Sequence . . . . . . . . . . . .                 *ALL  *MRG      00000-99999            <span style="color:blue">Numéro de séquence du projet M-Designer</span>
 Delete file  . . . . . . . . . .   N             Y, N                                   <span style="color:blue">Suppression du spool d'origine ?</span>
 Start page . . . . . . . . . . .   1             Integer, *SPL                          <span style="color:blue">Numéro de page de début</span>
 End page . . . . . . . . . . . .   999999        Integer, *SPL, *LAST                   <span style="color:blue">Numéro de page de fin</span>
 Original State . . . . . . . . .   'READY'       HOLD, READY                            <span style="color:blue">Statut de l'email ?</span>
 PRIORITY . . . . . . . . . . . .   '3'           1, 2, 3, 4, 5                          <span style="color:blue">Priorité d'envoi</span>
 Send from  . . . . . . . . . . .   *USER                                                <span style="color:blue">Emetteur de l'email</span>
 Send TO  . . . . . . . . . . . .    _______________________________________________     <span style="color:blue">Destinaire(s) de l'email</span>
 Send CC  . . . . . . . . . . . .    _______________________________________________     <span style="color:blue">Copie(s)</span>
 Send CCI . . . . . . . . . . . .    _______________________________________________     <span style="color:blue">Copie(s) cachée(s)</span>
 Subject  . . . . . . . . . . . .    _______________________________________________     <span style="color:blue">Sujet de l'email</span>
 Note . . . . . . . . . . . . . .    _______________________________________________     <span style="color:blue">Corps de l'email</span>
 Name of this file in the mail  .   'Doc.pdf'                                            <span style="color:blue">Nom du PDF envoyé par email</span>
 Path and name of the file  . . .    ________________________________________________    <span style="color:blue">Chemin d'une éventuelle autre pièce jointe</span>
 Name of this file in the mail  .    ________________________________________________    <span style="color:blue">Nom d'une éventuelle autre pièce jointe</span>
 Delete mail after send . . . . .   'N'           Y, N, O                                <span style="color:blue">Supprimer ou non l'email après son envoi</span>
 Delete file1 after send  . . . .   'N'           Y, N, O                                <span style="color:blue">Supprimer le 1er fichier joint</span>
 Delete file2 after send  . . . .   'N'           Y, N, O                                <span style="color:blue">Supprimer le 2ième fichier joint</span>
                           Autres paramètres
 Code Page  . . . . . . . . . . .   *SPL          *SPL, 037,1147                         <span style="color:blue">Spécifier un code page</span>
===A partir de la V10.1===
Depuis la version 10.1 de la suite OPALE, il est possible d'envoyer des emails en mode XPS en utilisant la conversion XPS to PDF.
Pour cela, 2 nouveaux paramètres sont apparus :

'''Type de langage  . . . . . . . . . . .   ________          *XPS <br>  '''
'''Imprimante XPS / Language  . . .   ________          Nom, *PDF,'''

It is then possible to use a XPS format to send an email (the native PDF generation is no longuer needed)

Type de langage  . . . . . . . . . . .   '''*XPS'''<br>  
Imprimante XPS / Language  . . .   '''*PDF '''

== Generality on the MAPSNDMAIL command== 
==What new from V10.8.0==

The 10.8.0 version bring new possibilites in regard to the emailing

===SMTP settings screen of the emailing===
Prior to V10.8.0, the SMTP setting was made with a variable system through the '''WRKENVVAR'' IBM-i command.
Now, this setting is no longer made from the WRKENVVAR commande but directly from the MAPPING emailing setting screen.

The screen is available only if you have *SECOFR authority


  <span style="background-color:Black;color:Lime;">SMTP server IP address                   Nom du serveur SMTP</span>
  <span style="background-color:Black;color:Lime;">SMTP server port (25)                    Numéro du port de connexion</span> 
  <span style="background-color:Black;color:Lime;">SMTP server Login                        Nom d'utilisateur pour la connexion au server SMTP</span>
  <span style="background-color:Black;color:Lime;">SMTP server Password                    Mot de passe pour la connexion au server SMTP</span>
  <span style="background-color:Black;color:Lime;">SMTP Protocol                           Protocole SMTP (SSL, DTLS, TLS1, TLS1.1, TLS1.2)</span>
  <span style="background-color:Black;color:Lime;">SMTP server domain                       Nom du domain du serveur SMTP</span> 
 <span style="background-color:Black;color:Lime;">Temp folder                         Répertoire temporaire (répertoire MAPSEND par défaut)</span>
 Le dossier temporaire est le dossier où sont stockés les fichiers PDF envoyés par mail, les utilisateurs
 envoyant des mails doivent avoir les droits d'accès en lecture et écriture sur ce répertoire 
 <span style="background-color:Black;color:Lime;">Data Queue processing                   <nowiki>***détail à compléter*** par défaut : MAPSMTP</nowiki></span>
 La DTAQ par défaut est MAPSMTP (créée à l'installation), c'est elle qui permet au robot Mapping
 d'envoyer automatiquement les spools au serveur de mail. Cette DTAQ doit exister. 
 <span style="background-color:Black;color:Lime;">Jobd for e-mailing                     <nowiki>***détail à compléter*** par défaut : MAPDSMTP2</nowiki></span>
 La JOBD par défaut est MAPDSMTP2 (créée à l'installation). Elle définit les propriétés des jobs d'envoi de mail par le robot. Cette JOBD doit exister. 
 <span style="background-color:Black;color:Lime;">Message on success                     <nowiki>***détail à compléter*** *USER</nowiki></span>
 Trois valeurs sont possibles :
 - *NONE. Par défaut, aucune commande n'est exécutée.
 - *USER. Par défaut, la commande SNDUSRMSG TOUSR(&USER) est exécutée.
 - *SYSOPR. Par défaut, la commande SNDUSRMSG TOUSR(*SYSOPR) est exécutée 
 <span style="background-color:Black;color:Lime;">Message on error                          <nowiki>***détail à compléter*** *USER</nowiki></span>
 Les réactions sur succès et sur erreur sont gérées dans le programme MAP_C031P9. Les sources de ce programme sont dans le fichier MAP_SPECIF de la bibliothèque d'installation.
 Trois valeurs sont possibles :
 - *NONE. Par défaut, aucune commande n'est exécutée.
 - *USER. Par défaut, la commande SNDUSRMSG TOUSR(&USER) est exécutée.
 - *SYSOPR. Par défaut, la commande SNDUSRMSG TOUSR(*SYSOPR) est exécutée
 <span style="background-color:Black;color:Lime;">SMTP debug level                          (SSL, DTLS, TLS1, TLS1.1, TLS1.2)</span>

===SMTP settings on the MAPSNDMAIL command===

Since version 10.8.0, it is possible to override the SMTP server parameter values at the command level. The email sent will then use the information entered in the order and will ignore, for this sending only, the parameters entered in the general configuration screen.

The '''*DFT''' value refers to the setting of the general configuration screen. This value can be changed.

<span style="background-color:Black;color:Lime;">Other parameters</span>

  <span style="background-color:Black;color:Lime;">SMTP server name or address (<nowiki>*DFT</nowiki>) SMTP server name</span>
   <span style="background-color:Black;color:Lime;">SMTP server port (<nowiki>*DFT</nowiki>) Connection port number</span>
   <span style="background-color:Black;color:Lime;">SMTP login name (<nowiki>*DFT</nowiki>)
   <span style="background-color:Black;color:Lime;">SMTP login password (<nowiki>*DFT</nowiki>) login password</span>
   <span style="background-color:Black;color:Lime;">SMTP protocol (<nowiki>*DFT</nowiki>) SMTP Prptocole</span>
   <span style="background-color:Black;color:Lime;">SMTP domain name (<nowiki>*DFT</nowiki>) Domain Name</span>

==Menus management== 


The menu for sending e-mail is called MAPSND. To access it, enter the command:
  GO MAPSND


[[FILE:MAPSND.jpg|500px]]

===1. Email settings===
====Before version 10.0====

This screen is only available if you have SECOFR rights


<span style="background-color:Black;color:Lime;">SMTP server IP address                   Nom du serveur SMTP</span>
 
 <span style="background-color:Black;color:Lime;">SMTP server port (25)                    Numéro du port de connexion</span> 
 
 <span style="background-color:Black;color:Lime;">SMTP server domain                       Nom du domain du serveur SMTP</span>
 
 <span style="background-color:Black;color:Lime;">Temporary folder                         Répertoire temporaire (répertoire MAPSEND par défaut)</span>
 Le dossier temporaire est le dossier où sont stockés les fichiers PDF envoyés par mail, les utilisateurs
 envoyant des mails doivent avoir les droits d'accès en lecture et écriture sur ce répertoire
 
 <span style="background-color:Black;color:Lime;">Waiting Dtaq                             <nowiki>***détail à compléter*** par défaut : MAPSMTP</nowiki></span>
 La DTAQ par défaut est MAPSMTP (créée à l'installation), c'est elle qui permet au robot Mapping
 d'envoyer automatiquement les spools au serveur de mail. Cette DTAQ doit exister. 
 
 <span style="background-color:Black;color:Lime;">Sending jobd                              <nowiki>***détail à compléter*** par défaut : MAPDSMTP2</nowiki></span>
 La JOBD par défaut est MAPDSMTP2 (créée à l'installation). Elle définit les propriétés des jobs d'envoi de mail par le robot. Cette JOBD doit exister.
 
 <span style="background-color:Black;color:Lime;">Action if success                        <nowiki>***détail à compléter*** *USER</nowiki></span>
 Trois valeurs sont possibles :
 - *NONE. Par défaut, aucune commande n'est exécutée.
 - *USER. Par défaut, la commande SNDUSRMSG TOUSR(&USER) est exécutée.
 - *SYSOPR. Par défaut, la commande SNDUSRMSG TOUSR(*SYSOPR) est exécutée
 
 <span style="background-color:Black;color:Lime;">Action if error                          <nowiki>***détail à compléter*** *USER</nowiki></span>
 Les réactions sur succès et sur erreur sont gérées dans le programme MAP_C031P9. Les sources de ce programme sont dans le fichier MAP_SPECIF de la bibliothèque d'installation.
 Trois valeurs sont possibles :
 - *NONE. Par défaut, aucune commande n'est exécutée.
 - *USER. Par défaut, la commande SNDUSRMSG TOUSR(&USER) est exécutée.
 - *SYSOPR. Par défaut, la commande SNDUSRMSG TOUSR(*SYSOPR) est exécutée

====From version 10.0====
From version MAPPING OPALE 10.1, a '''Mode used to send''' parameter is available:

Mode used to send ____________ (*MAPPING, *IBM)

These two possible values are: '''*MAPPING''' and '''*IBM'''

'''*MAPPING''' allows to have an identical behavior to previous versions of MAPPING. In other words, MAPPING manages the sending of emails via the SMTP settings stipulated below this same settings screen.

Traduire avec la voix
364 / 5 000
Résultats de traduction
Résultat de traduction
'''*IBM''' allows to let the IBM-i SMTP configuration (IBM-i API) take over for sending emails. The configuration of the SMTP server entered in this configuration screen is then not used.

===2. Starting mail management===
This menu is used to start the MAPSMTP job of the MAPSROBOT subsystem. This work must absolutely be started for sending mail via the MAPSNDMAIL command. This menu calls the STRMAPMAIL command.

===3. Stop email===
This menu is used to stop the MAPSMTP job of the MAPSROBOT subsystem. This menu calls the ENDMAPMAIL command.

===4. Displaying e-mail queue===
This menu allows you to display previously sent e-mails, which you can filter by user name. This menu calls the MAPDSPMAIL command.<br />
'''Caution''': This menu stops you from sending new e-mails so do not leave it open.

===5. Sending an e-mail===
This menu allows you to send an e-mail with (or without) an attachment. This menu calls the MAPSNDDST command.

===6. Sending a spool by mail===
This menu allows the layout of an IBM i spool file as well as its conversion into PDF and its sending by e-mail. This menu calls the MAPSNDMAIL command.

===7. Checking e-mail operations===
This menu lists the jobs of the sub-system that are linked to e-mailing (MAPSMTP in this case).

===8. Managing spooled files (MAPPING interactive run)===
This menu allows you to manage spooled files. This feature is the same as option 1 of the GO MAPPING menu. This menu calls the COGISPLF command.

==Keywords used to automatically map data from input spool file==
As seen previously, a prerequisite for the MAPSNDMAIL command is the design of a Designer model with generation in PDF language.
To obtain the content of the spool file directly in the body of the e-mail or to have the address of the recipient and the sender taken from the spool file, there are several zones in Designer (type of METADATA zone):
===List of keywords===
*mapFrom: Used to take the sender's email address from the spool file
*mapSend: Used to take sender's recipient email address from spool file
*mapCopy: Used to take the copy email address from the spool file
*mapBCopy: Used to take cached copy email address from spool file
*mapNote: Used to take data from the spool file and put it into the body of the sent email
*mapSubject: Used to take data from the spool file and put it into the subject of the sent email

===Using keywords===
To use the keywords configured in the Designer project (listed below), you need to reference them in the MAPSNDMAIL command.


To do so, here are the parameters of the MAPSNDMAIL command listed with their corresponding values:


{| class="wikitable"
! Name of the parameter of the MAPSNDMAIL command
! Value to reference Designer meta data
|-
| Send FROM (FROM)
| *MAPFROM
|-
| Send TO (TO)
| *MAPSEND
|-
| Send CC (CC)
| *MACOPY
|-
| Send BCC (CCI)
| *MAPBCOPY
|-
| Subject (SUBJECT)
| *MAPSUBJCT
|-
| Note (NOTE)
| *MAPNOTE
|}

==Configuration== 

===Configuring the environment variable to define the e-mail sender===
The sender's e-mail address and its password must be configured in the environment variables of the MAPPING Server.
To do so, follow the steps below: 


1) Run command:
 WRKENVVAR


2) Create the environment variables in *SYS so that the Mapping sub-system which contains the e-mail address and the password for the SMTP server authentication can work.
 <span style="background-color:Black;color:Lime;">MAIL_PASSWORD                MYPASSWORD</span> 
 <span style="background-color:Black;color:Lime;">MAIL_LOGIN                   MYEMAILADDRESS</span> 


The sender's e-mail address specified in the MAPSNDMAIL command has to be MYEMAILADDRESS.


Note: To send an e-mail from dynamic e-mail addresses (coming from the spooled file for instance), you can configure the SMTP server to allow e-mails to be sent from any given e-mail address.

===Configuring the server to send e-mails===
Select option 1 of the GO MAPSND menu to fill in information about the server:
* Server IP address
* Server port
* Server domain


'''Caution''': You need to have SECOFR permissions or access to the menu will be denied and the messages won't be displayed.

=== Security Setting ===

⚠ Parameterization present from Opale v10.5.0

The secure connection mode is TLS v1.2 by default.

However, it is possible to switch to other less frequent or less secure modes by setting an environment variable <code>EMAILPROTOCOL</code>.

This parameter takes a numerical value between 1 and 5. The absence of this parameter leads to the choice of TLS v1.2.

{| class="wikitable"
! Valeur
! Protocol
|-
| 1
| SSL v3
|-
| 2
| DTLS v1
|-
| 3
| TLS v1.0
|-
| 4
| TLS v1.1
|-
| 5 (par défaut)
| TLS v1.2
|}

==Text or HTML content==
Since version 10.4.0 of MAPPING IBM-i, it is possible to specify the type of content (Text or HTML) of the body of emails.
===Text Content===
It is possible to specify in text the type of content of the email sent by the MAPSNDMAIL command. To do this, you must prefix the content of the body with %%TXT%% or %%FILE_TXT%%

%%TXT%%: Allows the body to be sent in text mode (default value) <br>
Example: %%TXT%%Here is the body of my email in text


%%FILE_TXT%%: The content of the email will then be the content of a file sent in text mode
Example: %%FILE_TXT%%/home/mybody.txt (File encoded in ANSI)

===HTML content===
It is possible to specify in HTML the type of content of the email sent by the MAPSNDMAIL command. To do this, you must prefix the body content with %%HTML%% or %%FILE_HTML%%

%%HTML%%: Allows you to send the body in HTML mode<br>
Example: %%HTML%%Here is the body of my email in <b>html</b>


%%FILE_HTML%%: The content of the email will then be the content of a file sent in HTML mode
Example: %%FILE_HTML%%/home/mybody.html (File encoded in ANSI)



==Examples==

===Sending an email with a PDF file attached===
 <span style="background-color:Black;color:Lime;">MAPSNDMAIL SPLF(INVOICE) SPLNUM(23) JOB(QPADEV0009) JOBNUM(855068) USER(JDIEU) MAPNAM(MAIL_DOC) MAPSEQ(00010) DELSPL(N) PAGSTR(1) PAGEND(10) STATE(READY)FROM('hotline@mappingsuite.onmicrosoft.com')
 TO('jdieu@mappingsuite.onmicrosoft.com') SUBJECT('My subject') NOTE('This is the body of the e-mail') NAME1('PJ.pdf')</span>

===Sending an email with dynamic text in the e-mail body===
 <span style="background-color:Black;color:Lime;">MAPSNDMAIL SPLF(INVOICE) SPLNUM(23) JOB(QPADEV0009) JOBNUM(855068) USER(JDIEU) MAPNAM(MAIL_DOC) MAPSEQ(00010) DELSPL(N) 
 PAGSTR(1) PAGEND(10) STATE(READY) FROM('hotline@mappingsuite.onmicrosoft.com') 
 TO('jdieu@mappingsuite.onmicrosoft.com') SUBJECT('My subject') NOTE('This is the body of my e-mail with dynamic data:<nowiki>[[DATE]]</nowiki>') NAME1('PJ.pdf')</span>

===Sending an e-mail with dynamic HTML code in the e-mail body===


The aim of this feature is to use an HTML file as the body for the e-mail.


<u>Example of an HTML file (mail.html) </u>:


''<nowiki><body></nowiki>
 <nowiki><img src="http://www.mappingsuite.com/wp-content/uploads/2018/08/Logo_web1.png"></nowiki>
 <nowiki>Dear Sir [[NAME]] client number [[CLINUM]],</nowiki>
 <nowiki>Please find attached our invoice n&ordm; <font color=red> [[INVNUM]] from [[DATE]] </font></nowiki>.
 <nowiki><b>Regards</b></nowiki>
 </body>''
<u>Caution</u>: Special characters have to be written with appropriate coding in the HTML file: 
https://www.commentcamarche.com/contents/489-caracteres-speciaux-html


To call the HTML file, you need to specify its path and name in the NOTE parameter of the MAPSNDMAIL command:

<span style="background-color:Black;color:Lime;">MAPSNDMAIL SPLF(INVOICE) SPLNUM(23) JOB(QPADEV0009) JOBNUM(855068) USER(JDIEU) MAPNAM(MAIL_DOC) MAPSEQ(00010) DELSPL(N)
  PAGSTR(1) PAGEND(10) STATE(READY) FROM('hotline@mappingsuite.onmicrosoft.com')
  TO('jdieu@mappingsuite.onmicrosoft.com') SUBJECT('My subject') <u>NOTE('%%FILE_HTML%%/home/mapsend/mail.html')</u> NAME1('PJ.pdf ')</span>

<u>Here is the final result</u>:

[[FILE:LOGOMAPPING.jpg|50px]]<br />
Dear Sir MICALETTI client number 9214, 

Please find attached our invoice nº<span style="color:Red;"> 1 from 11/23/2016. 

'''Regards'''

==Troubleshooting== 

To solve the emailing issues via the MAPSNDMAIL command, you can refer to the following page :

[[OPALE:10.0:KB:Erreur_MAPSNDMAIL|Résolution d'erreurs d'envoi de mail]]

==Other links==


[[OPALE:10.0:Utilisation:_Paramétrage_du_mail|Paramétrage de l'envoi de mail]]
Mot clé : MAPSNDMAIL, Envoi email, envoi PDF par mail, Mail