How do you parameterize the "TMAIL_C" instruction to send e-mails with the SIMATIC S7-1200 and S7-1500?
The "TMAIL_C" instruction uses the SMTP (Simple Mail Transfer Protocol) to send an e-mail via the Ethernet interface of the S7-1200 > V4.0 or a communications processor (CP).
Using the "TMAIL_C" instruction, with version V4.0 and higher you can send e-mails via Secure Communication through the Ethernet interface of the following modules:
- CP 1543-1 V2.0
- CP 1542SP-1 IRC V1.0
- CP 1543SP-1 V1.0
- CP 1243-1 V2.1 and higher
- CP 1242-7 GPRS V2 V2.1 and higher
- CP 1243-7 LTE V2.1 and higher
- CP 1243-8 V2.1 and higher
Via the system data type "TMAIl_V4_SEC", "TMAIL_V6_SEC" or "TMAIL_QDN_SEC" you define the data necessary for sending the e-mail including the TCP port of the e-mail server.
For the sake of compatibility you can also use the previous system data types "TMAIL_V4", "TMAIL_V6" and "TMAIL_FQDN". In this case you can also send an e-mail via the Ethernet interfaces of the CPUs and the Ethernet interface of the CP 1543-1.
In this example an e-mail is sent via an Ethernet-based internet connection. The following hardware components are used:
- S7-1200 CPU
- DSL router for access to the internet
The figure below shows the call of the "TMAIL_C" instruction including instance data block DB1 and an example of how to parameterize the inputs and outputs of the "TMAIL_C" instruction.
Inputs of the "TMAIL_C" instruction
Table 01 shows the inputs of the "TMAIL_C" instruction.
REQUEST: Activates the sending of an e-mail on occurrence of a rising edge.
Recipient addresses, for example: <email@example.com>,
Recipient address for the CC copy (optional), for example: <firstname.lastname@example.org>
The following rules must be followed for entering the parameter:
|SUBJECT||String||Subject of the e-mail|
Text of the e-mail (optional)
Attachment of the e-mail (optional)
Reference to a byte/word/double-word field (ArrayOfByte, ArrayOfWord or ArrayOfDWord) with a maximum length of 64 bytes. If no value is set, the e-mail is sent without attachment.
Name of the e-mail attachment (optional)
Reference to a character string with a maximum length of 50 characters (bytes) to define the file name of the attachment. If an empty string is assigned to this parameter, the attachment of the e-mail is sent with the file name "attachment.bin".
Parameters of the connection and address of the e-mail server.
Use the TMail_V4 structure to define the connection parameters.
Outputs of the "TMAIL_C" instruction
Table 02 shows the outputs of the "TMAIL_C" instruction.
Return value or error information of the "TMAIL_C" instruction
At the MAIL_ADDR_PARAM parameter you define in the "TMail_V4" structure the connection via which the e-mail is to be sent and save the address of the e-mail server and the login data.
Table 3 shows the "TMAIL_V4" structure for addressing the e-mail server via the IP address according to IPv4.
Hardware ID of the interface
Monitoring of the execution time. You use this parameter to define the maximum execution time of the send procedure.
|MailServerAddress||IP_V4||IP address of the mail server. According to IPv4 in the format xxx.xxx.xxx.xxx (decimal).|
|UserName||STRING||Login name of the mail server|
|PassWord||STRING||Password of the mail server|
Address of the e-mail sender defined by the following two STRING parameters.
For example: "email@example.com"
Local part of the sender address including @ character.
For example: "test@"
Fully Qualified Domain Name (FQDN) of the mail server.
For example: "testmail.os"
Fig. 2 shows an example of parameterizing the "TMail_V4" structure in a global data block.
- In the CPU you must activate the router and set the correct IP address of the router. Otherwise the CPU cannot reach the public IP address of the e-mail server.
- Via the Ethernet interface of the CPU the TMAIL_C instruction can communicate with an e-mail server using SMTP via Port 25. The assigned port number cannot be changed.
- Via the CP the "TMAIL_C" instruction can establish a secure connection (SMTP over TSL) to an e-mail server.
In company networks which only permit internet access by proxy and usually block all the other ports including Port 25, you cannot use the "TMAIL_C" instruction to establish a connection to external e-mail servers via the Ethernet interface of the CPU . It must be possible to communicate externally over the TCP Port 25.
You can establish a connection through SMTP with an internal e-mail server and let the internal server manage the current security extensions required to forward e-mails via the internet to an external e-mail server.
Alternatively you can use a CP to establish a secure connection (SMTP over TSL) to an e-mail server with the "TMAIL_C" instruction.
The application example "Send e-mails to SMTP server with an S7-CPU" describes the following tasks :
- Configure the Jana Server as internal mail server to forward an e-mail to an external mail server.
- Establish a secure connection (SMTP over TSL) to an e-mail server via the CP.
- You should always implement Defense in Depth before connecting a CPU to the internet.
- In the Security Siemens Operational Guidelines we give clear recommendations about how to act when connecting control components with office servers, in this example the e-mail server . It might be necessary to use a DMZ solution.
More information is available in the STEP 7 (TIA Portal) manual under Description of TMAIL_C (S7-1200, S7-1500).