×
Siemens Industry Online Support
Siemens AG
Entry type: FAQ Entry ID: 67262019, Entry date: 04/06/2018
(14)
Rate

How do you parameterize the "TMAIL_C" instruction to send e-mails with the SIMATIC S7-1200 and S7-1500?

  • Entry
  • Associated product(s)
Using the "TMAIL_C" instruction to send e-mails with the SIMATIC S7-1200 and SIMATIC 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.

Hardware requirements
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.
  


Fig. 1

Inputs of the "TMAIL_C" instruction
Table 01 shows the inputs of the "TMAIL_C" instruction.
     

InputData typeDescription
REQBOOLControl parameter
REQUEST: Activates the sending of an e-mail on occurrence of a rising edge.
TO_SString

Recipient addresses, for example: <user1@jana.os>,

 Note
The following rules must be followed for entering the parameter:

  • A space and opening pointed bracket "<" must be entered before each e-mail address.
  • A closing pointed bracket ">" must be entered after each address.
  • A comma must be entered between the addresses in TO_S and CC.
CCString

Recipient address for the CC copy (optional), for example: <user2@jana.os>

Note

The following rules must be followed for entering the parameter:

  • A space and opening pointed bracket "<" must be entered before each e-mail address.
  • A closing pointed bracket ">" must be entered after each address.
  • A comma must be entered between the addresses in TO_S and CC.
SUBJECTStringSubject of the e-mail
TEXTString

Text of the e-mail (optional)

Note
If an empty string is assigned to this parameter, the e-mail is sent without a text.

ATTACHMENTVariant

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. 

ATTACHMENT_NAMEString

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". 

MAIL_ADDR_PARAMVariant

Parameters of the connection and address of the e-mail server.

Use the TMail_V4 structure to define the connection parameters.

Table 1

Outputs of the "TMAIL_C" instruction
Table 02 shows the outputs of the "TMAIL_C" instruction.
 

Output Data type Description
DONE BOOL

Status parameter

  • DONE = 0: Job not yet started or is still being executed
  • DONE = 1: Job executed error-free
BUSY BOOL

Status parameter

  • BUSY = 0: Processing of "TMAIL_C" has finished
  • BUSY = 1: Sending of the e-mail has not been completed
ERROR BOOL

Status parameter

  • ERROR = 0: No error occurred
  • ERROR = 1: An error has occurred during processing. STATUS provides detailed information about the type of error.
STATUS Word

Status parameter

Return value or error information of the "TMAIL_C" instruction

Table 2

Parameter "MAIL_ADDR_PARAM"
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.
      

ParameterData typeDescription
TMail_V4Struct 
InterfaceIDLADDR

Hardware ID of the interface

IDCONN_OUC

Connection ID

ConnectionTYpeBYTE

Connection type
For IPv4 you select 16#20 as connection type.

ActiveEstablishedBOOL

Status bit
Set to "1" when the connection is established.

CertIndexBYTE
  • = 0: Utilization of SMTP (Simple Mail Transfer Protocol). SMTP must be used for sending an e-mail via the interface of an S7-1200 CPU.
  • ≠ 0: Utilization of SMTPS to secure the connection before establishment of the connection (for CPs/CMs). You use the CertIndex parameter to specify the certificate to be used (see "Project Navigation > Global Security Settings > Certificate Manager").

WatchDogTimeTIME

Monitoring of the execution time. You use this parameter to define the maximum execution time of the send procedure. 

Note
In the case of a slow connection the establishment of the connection can take longer (about one minute). You must take the connection establishment time into account when setting the "WatchDogTime" parameter. After the specified time has expired the connection is disconnected.

MailServerAddress IP_V4 IP address of the mail server. According to IPv4 in the format xxx.xxx.xxx.xxx (decimal). 
UserNameSTRING[254]Login name of the mail server 
PassWordSTRING[254]Password of the mail server
FromEMAIL_ADDR

Address of the e-mail sender defined by the following two STRING parameters.

For example: "test@testmail.os"

LocalPartPlusAtSignSTRING[64] 

Local part of the sender address including @ character.

For example: "test@" 

FullQualifiedDomainNameSTRING[254] 

Fully Qualified Domain Name (FQDN) of the mail server.

For example: "testmail.os" 

Table 3

Fig. 2 shows an example of parameterizing the "TMail_V4" structure in a global data block.
 

Fig. 2

Note

  • 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 (SNMP 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.

Note

  • 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.

Further Information
More information is available in the STEP 7 (TIA Portal) manual under Description of TMAIL_C (S7-1200, S7-1500).

Security information
In order to protect technical infrastructures, systems, machines and networks against cyber threats, it is necessary to implement – and continuously maintain – a holistic, state-of-the-art IT security concept. Siemens’ products and solutions constitute one element of such a concept. For more information about cyber security, please visit
https://www.siemens.com/cybersecurity#Ouraspiration.