SMTP API

Send a message to a natural person or a company using a normal email application by selecting the Send message function. The message to be sent is created as shown in Table 1.

Table 1. The fields used for sending a message and the data to be entered into them.

Picture 1 shows an example of a message that has been written according to the instructions.

Picture: 1. Example of a view of sending a new message from the email software to an end user.

Show larger picture

• delivery of your organisation’s message to the Messages service or a failure to deliver the message
• the end user has read the message they have received
• the end user has acknowledged the receipt of the message (verifiable notification, which cannot be sent through the SMTP API but requires a WS API or an SFTP API connection).

It is important to note that you cannot reply to status reports. Picture 2 shows an example of a confirmation of a successful delivery. Picture 3 and Picture 4, on the other hand, describe examples of situations in which the message failed to be forwarded.

Picture: 2. Confirmation of successful message delivery to the end user.

Show larger picture

Picture: 3. The status of the end user’s mailbox is not active, so the status confirmation contains an error.

Show larger picture

Picture: 4. The end user was not found in the Messages service registry, so the status confirmation returns an error. This is a possible event if, for example, the personal identity code has been entered incorrectly.

Show larger picture

Picture: 5. Confirmation of a successfully delivered message that has been read by the end user.

Show larger picture

An end user can send messages to your organisation or reply to a message you have sent if your organisation has enabled two-way communication in Suomi.fi Messages.

When the end user sends a message with the Write a message feature in Suomi.fi Messages, the message is delivered to the address your organisation has configured in Suomi.fi Messages. When the end user replies to a message sent by your organisation, the reply is sent to the email address which you used to send the original message. In addition, the reply is forwarded to the address that was in the reply-to field of the original message.

The e-mail address associated with a message sent by an end user is TUNNISTE@asiointitili.fi, in which TUNNISTE is replaced with the sender's personal identity code (natural person) or business ID (company). Replying to the message is simply done using the reply function of the e-mail program. When replying, it is very important to ensure that any original message that is automatically attached to the reply is completely deleted so that the end user’s identifier data is not transmitted incorrectly. However, the subject line of the e-mail message may not be changed or deleted. Picture 6 shows a situation in which the original message should be deleted.

Picture: 6. An example of a view in which the e-mail program has automatically attached the original message to a reply that should be deleted before the reply is sent.

Show larger picture

Your organisation is responsible for ensuring that the SMTP API is used appropriately. Below is a list of factors that should be considered when using the interface.

Data protection

Your organisation is responsible for ensuring that the messages your organisation receives via the SMTP API are not forwarded to unsecured email addresses. The data protection level of Suomi.fi Messages is higher than in ordinary emails, and forwarding messages may endanger the privacy of the messages.

The Cc and Bcc fields must also be left empty when messages are sent via the SMTP API. 

The reply-to field enables your organisation to specify a different reply address to the messages it sends. This ensures that a single person is not responsible for replying to an end user’s reply messages. The address entered in the reply-to field must belong to the same email domain your organisation uses which is connected to the Messages service.

Suomi.fi Messages use the personal identity code as an internal identifier. It is forwarded to the client organisation in a message sent from Suomi.fi Messages. In an email-connected service, the personal identity code is displayed in the body of the message in the section ‘Viestin tiedot’ (Message details) and in the sender’s address (PERSONALID@asiointitili.fi). When the end user is sent a reply, the Message details section should be deleted from the message body as described in the instructions "Receiving a message sent by the end user and replying to it".

Acting on behalf of another party

A person can also act on behalf of another person or company, in which case this person is called an agent. It is possible to include the agent’s details in the content of the email message to be received. In that case, the version of the return channel must be defined as 2.0 in client- and service-specific settings. When this interface version has been enabled, the details of the agent will appear at end of the email message.

Archiving sent and received messages

Your organisation must archive the messages sent and received via the SMTP API to the extent necessary for your operations. Messages are stored in Suomi.fi Messages only for the end user, and the organisation that sent the message does not have access to them.

Possible configurations for an organisation’s email server

Your organisation is responsible for ensuring that the interface between your own email server and the email server of Suomi.fi Messages and the methods used for encrypting messages are compliant with the guidelines issued by Digital and Population Data Services Agency.

Instructions for the recipient attached to an email message

Your organisation must create instructions that ensure that the message recipient is provided with the necessary instructions.

Restrictions on the content of attachments

The file types and size of the attachments that can be sent and received in Suomi.fi Messages are restricted. The allowed file formats are described on the page Content of an electronic message.

If your organisation sends a message with an attachment that is not an allowed file type, Suomi.fi Messages will respond with a confirmation message that states the reason for the error.