×
Siemens Industry Online Support
Siemens AG
  • Content
  • Search
  • Index
  • STEP 7 and WinCC Engineering V15.1
    • Programming the PLC
      • Instructions
        • Instructions (S7-1200, S7-1500)
          • Communication (S7-1200, S7-1500)
            • Open User Communication (S7-1200, S7-1500)
              • Data consistency (S7-1200, S7-1500)
              • Program example for send functions (S7-1200, S7-1500)
              • TMAIL_C: Transfer email (S7-1200, S7-1500)
                • Description of TMAIL_C (S7-1200, S7-1500)
                • Description TMAIL_C as of version V4.0 (S7-1200, S7-1500)
                • Description of TMAIL_C as of version V5.0 (S7-1200, S7-1500)
                • TO_S and CC parameters (S7-1200, S7-1500)
                • MAIL_ADDR_PARAM parameter (S7-1200, S7-1500)
                • Parameter MAIL_ADDR_PARAM as of Version 4.0 of TMAIL_C (S7-1200, S7-1500)
                • DONE, BUSY and ERROR parameters (S7-1200, S7-1500)
                • STATUS parameter (S7-1200, S7-1500)
                • Example: Sending an e-mail with TMAIL_C (S7-1200, S7-1500)
    (27)
    Rate

    Entry type: Manual, Entry ID: 109755202, Entry date: 10/16/2018

    SIMATIC STEP 7 Basic/Professional V15.1 and SIMATIC WinCC V15.1

    Document: STEP 7 and WinCC Engineering V15.1 (10/2018, English)
    Type of topic: Fact

    Description of TMAIL_C (S7-1200, S7-1500)

    Description

    You can use the "TMAIL_C" instruction to send an e-mail via the Ethernet interface of the S7-1500 CPU or S7-1200 > V4.0, a communication module (CM), or a communication processor (CP).

    The instruction can only be used once the hardware has been configured and if the network infrastructure allows for a communication connection to the mail server.

    You define the content of the e-mail, and the connection data, using the following parameters:

    • You define the recipient addresses with the parameters TO_S and CC.
    • You define the content of the e-mail with the parameters SUBJECT and TEXT.
    • You can define an attachment using VARIANT pointers at the ATTACHMENT and ATTACHMENT_NAME parameters.
    • The connection data is defined, and addressing and authentication for the mail server executed, using the system data type TMail_V4, TMail_V6 or TMail_FQDN at the MAIL_ADDR_PARAM parameter.
      • - If you are using the interface of the S7-1500 CPU, the system data type TMail_V4 must be used. In this case, the e-mail can only be sent via SMTP.
      • - Any of the system data types can be used if you are using the interface of a CM/CP. The e-mail can then also be sent via SMTPS.
    • You start the sending of an e-mail with an edge change from "0" to "1" for the REQ parameter.
    • The job status is indicated by the output parameters "BUSY", "DONE", "ERROR" and "STATUS".

    You cannot send an SMS directly with the "TMAIL_C" instruction. Whether or not the e-mail can be forwarded by the mail server as an SMS depends on your telecommunications provider.


    Note

    Number of e-mails to be sent

    You can send more than one e-mail simultaneously using a PLC. When a CP 1243-8 or CP 1543-1 is used, you can only send one e-mail for each CP. When two CPs are used, parallel sending of two e-mails is possible.



    Operation of the instruction

    The "TMAIL_C" instruction works asynchronously, which means its execution extends over multiple calls. You must specify an instance when you call the instruction "TMAIL_C".

    In the following cases, the connection to the mail server will be lost:

    • If the CPU switches to STOP while "TMAIL_C" is active.
    • If communication problems occur at the Industrial Ethernet bus.

    In this case, the transfer of the e-mail will be interrupted and it will not reach its recipient. The connection is also canceled once the instruction has been successfully executed and the e-mail sent.


    Notice

    Changing user programs

    You can change the parts of your user program that directly affect calls of "TMAIL_C" only:

    • The CPU is in "STOP" mode.

    • No e-mail is being sent (REQ = 0 and BUSY = 0).

    This relates, in particular, to deleting and replacing program blocks that contain "TMAIL_C" calls or calls for the instance of "TMAIL_C".

    Ignoring this restriction can tie up connection resources. The automation system can change to an undefined status with the TCP/IP communication functions via Industrial Ethernet.

    A warm or cold restart of the CPU is required after the changes are transferred.



    Data consistency

    The TO_S, CC, SUBJECT, TEXT, ATTACHMENT and MAIL_ADDR_PARAM parameters are applied by the "TMAIL_C" instruction while it is running, which means that they may only be changed after the job has been completed (BUSY = 0).

    SMTP authentication

    Authentication refers here to a procedure for verifying identity, for example, with a password query.

    If you are using the S7-1500 CPU interface, the instruction "TMAIL_C" supports the SMTP authentication procedure AUTH-LOGIN which is required by most mail servers. For information about the authentication procedure of your mail server, please refer to your mail server manual or the website of your Internet service provider.

    • Before you can use the AUTH-LOGIN authentication procedure, the "TMAIL_C" instruction requires the user name with which it is to log on to the mail server. This user name corresponds to the user name with which you set up a mail account on your mail server. It is transferred via the UserName parameter to the structure at parameter MAIL_ADDR_PARAM.

      If no user name is specified at the MAIL_ADDR_PARAM parameter, the AUTH-LOGIN authentication procedure is not used. The e-mail is then sent without authentication.

    • To log on, the "TMAIL_C" instruction also requires the associated password. This password corresponds to the password you specified when you set up your mail account. It is transferred via the PassWord parameter to the structure at parameter MAIL_ADDR_PARAM.

    Parameters

    The following table shows the parameters of the "TMAIL_C" instruction:

    Parameter

    Declaration

    Data type

    Memory area

    Description

    REQ

    Input

    BOOL

    I, Q, M, D, L, T, C or constant

    Control parameter REQUEST: Activates the sending of an e-mail upon a rising edge.

    TO_S

    Input

    STRING

    D, L or constant

    Recipient addresses

    STRING with a maximum length of 240 characters (bytes).

    For the e-mail address format, see the example in the parameter description.

    CC

    Input

    STRING

    D, L or constant

    CC recipient addresses (optional)

    STRING with a maximum length of 240 characters (bytes).

    Same e-mail address format as for the TO_S parameter. If an empty string is assigned here, the e-mail is not sent to a CC recipient.

    SUBJECT

    Input

    STRING

    D, L or constant

    Subject of the e-mail

    STRING with a maximum length of 240 characters (bytes).

    TEXT

    Input

    STRING

    D, L or constant

    Text of the e-mail (optional)

    STRING with a maximum length of 240 characters (bytes). If an empty string is assigned at this parameter, the e-mail is sent without text.

    ATTACHMENT

    Input

    VARIANT

    D

    E-mail attachment (optional)

    Reference to a byte/word/double word field (ArrayOfByte, ArrayOfWord or ArrayOfDWord) with a maximum length of 64 Kb. If no value is assigned, the e-mail is sent without an attachment.

    ATTACHMENT_NAME

    Input

    STRING

    D, L or constant

    E-mail attachment name (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 at this parameter, the attachment of the e-mail is received with a file name assigned by the e-mail receiving program. It is therefore recommended to use a defined file name.

    MAIL_ADDR_PARAM

    Input

    VARIANT

    D

    Connection parameter and address of the e-mail server

    To define the connection parameters, use the structure TMail_V4, TMail_V6 or TMail_FQDN (see parameter description).

    DONE

    Output

    BOOL

    I, Q, M, D, L

    Status parameter

    • DONE = 0: Job not yet started or still executing.
    • DONE = 1: Job executed without errors.

    BUSY

    Output

    BOOL

    I, Q, M, D, L

    Status parameter

    • BUSY = 0: Processing of "TMAIL_C" was terminated
    • BUSY = 1: Sending of an e-mail is not yet complete.

    ERROR

    Output

    BOOL

    I, Q, M, D, L

    Status parameter

    • ERROR = 0: No error occurred.
    • ERROR = 1: An error occurred during processing. STATUS supplies detailed information on the type of error.

    STATUS

    Output

    WORD

    I, Q, M, D, L

    Status parameter

    Return value or error information of the "TMAIL_C" instruction (see parameter description).

    You can find additional information on valid data types under "Overview of the valid data types".


    Note

    Optional parameters

    The optional parameters CC, TEXT, and ATTACHMENT are only sent with the e-mail if the corresponding parameters contain a string of length > 0.



    Example

    You will find an example of sending e-mails with the TMAIL_CExample: Sending an e-mail with TMAIL_C (S7-1200, S7-1500) instruction with the following link:



     

    Support to the statistics
    With this function the IDs found are listed according to number (format .txt).

    Generate list
    Copy URL
    Display page in new design
    mySupport Cockpit
    Related links