SFTP API

Please note that the old Suomi.fi Messages APIs are in maintenance mode, and no new functionalities are produced for them as a rule. All old APIs will be closed on 1 January 2027. This means that all services using Suomi.fi Messages must switch to the new REST interface before 2027.

Your organisation can use the SFTP interface to send materials (files and documents) to end users. The use of the SFTP API always requires a printing contract and enables the distribution of material both in electronic format and as paper mail.

The personal identity codes (SSN) in the control data (XML file) are used to check whether a person is using Suomi.fi Messages:

<Recipient emailAddress="recipient1@nnn.nn" customerCode="1111" phoneNumber="11111111" SSN="111111-1111">

When the end user is a company, an EDI code (ovtID) is added to the control data (XML file) instead of the personal identity code. The business ID contained in the EDI code is used to check whether the end user is using Suomi.fi Messages:

<Recipient …ovtID="003712345678"...</Recipient>

Messages can only be sent to Finnish companies (EDI codes beginning with 0037). The EDI code (0037NNNNNNNTBBBBB) and the business ID contained in it (NNNNNNN-T) are validated but the existence of the business ID in the Business Information System is not checked.

If an end user does not use Suomi.fi Messages, official messages are sent as traditional paper mail, as before.

After the SFTP transfer is complete, your organisation’s system receives a technical acknowledgment that the FTP service of the Shared Integration Platform (VIA) has received the file. In order for Suomi.fi Messages to send an acknowledgment that the electronic messages have been delivered, your organisation must have adopted the use of an interface that supports two-way messaging.

Your organisation transfers the materials as an SFTP transfer to the VIA service.

Each organisation must have their own user ID for the SFTP transfer. Your organisation submits an user ID request for SFTP transfer to the Digital and Population Data Services Agency that coordinates the SFTP connection process. In addition to the user ID, a telecommunications connection must be opened between your organisation and the VIA service. This requires that your organisation fills in a telecommunications opening form and submits it to the Digital and Population Data Services Agency.

To enable the SFTP transfer, an FTP user ID and password are created and delivered to your organisation by encrypted email. Your organisation can also adopt an certificate-based identification method for the SFTP connection as described below.

Method 1: Your organisation creates a PKI key pair and stores the private part of the certificate into its SFTP home directory. If RSA or DSA is used, the key pair must be at least 2048 bits.

Your organisation creates a key pair.
Your organisation delivers the public key to VIA.
The public key is installed in the ID.
Your organisation can now start using the ID.

Method 2: Your organisation asks the VIA service to create a certificate.

The VIA service creates the key pair and sets a passphrase to it.
The VIA service delivers the private key and password by secure mail to your organisation.
The public part is installed on the VIA ID and your installs the certificate on the program that performs the transfer.
Your organisation can now start using the ID.

File transfer supports the SFTP:put operation, by which your organisation transfers the material to the VIA service.

The SFTP IDs and directories are organisation-specific, which means that the content of the directory cannot be seen by other organisations. Only lowercase and uppercase letter are allowed in the name of the material to be transferred. Scandinavian characters, special characters and spaces are not allowed.

The material delivered by your organisation will be forwarded from the VIA service to Suomi.fi Messages. During the transfer, material in the VIA directory is transferred into the Arkisto (Archive) directory. The VIA service deletes the material in the Arkisto directory after 30 days.

The sender of the materials is responsible for ensuring that the transfer is successful, and that the same file is not transferred twice. The materials must be transferred with the SFTP:put operation to the directory in the VIA service first by using a temporary name. The sender renames the file to signify a successful transfer.

NOTE! Suomi.fi-messages has a following limit: the biggest size of the file (zip) is 80 Mb. The average size of the page in the received material is max 4MB (size of the material / number of pages). Maximum size of an individual message is 10 Mb.

The number of pages in a single letter is not limited, when the letter is printed in black and white. The maximum recommended number of pages is 2 000, but a PDF file/batch of 20 000 pages is also possible. In colour printing (color iPost PDF), the maximum number of pages in a single letter is 60.

The name of the file is used to direct the material to the correct printing service provider for paper printing. The sender must have a valid agreement with the printing service provider.

Naming of the file should be according to the Design instructions for sending letters (Posti)Opens in a new window.. In addition Suomi.fi Messages obliges that the identifier of printing service provider is included in the end of file name separated with underscore

<filename>_<identifier of printing service provider>.zip

We recommend that each material file is uniquely named, for example by adding timestamp or UUID to the filename, e.g.

Vaka_20180524145451_posti.zip

Letters on paper are printed by a printing service. The SFTP API is compliant with Posti Messaging's iPost service. The specifications can be found in the Design instructions for sending letters (Posti)Opens in a new window..

In addition to Posti Messaging Oy's specifications, Suomi.fi Messages expects the additional information detailed in Table 1 to be included in the control data.

Field	Explanation
lb:Letter:senderLetterID	Unique identifier for the sender's letter. The identifier must be unique within the sending service (the service + senderLetterID are together always globally unique). Mandatory.
lb:Sender:email	Your organisation's email address. Used for sending information regarding possible errors. Mandatory.
Pakollisena jompi kumpi: lb:Recipient:SSN tai lb:Recipient:ovtID	The recipient's personal identity code (SSN) or company's EDI code (ovtID). Used for checking whether the recipient has an electronic mailbox in Suomi.fi Messages and electronic delivery. Mandatory.

Field

Explanation

lb:Letter:senderLetterID

Unique identifier for the sender's letter.

The identifier must be unique within the sending service (the service + senderLetterID are together always globally unique).

Mandatory.

lb:Sender:email

Your organisation's email address.

Used for sending information regarding possible errors.

Mandatory.

Pakollisena jompi kumpi:

lb:Recipient:SSN tai lb:Recipient:ovtID

The recipient's personal identity code (SSN) or company's EDI code (ovtID).

Used for checking whether the recipient has an electronic mailbox in Suomi.fi Messages and electronic delivery.

Mandatory.

Table 1. The additional control data required by Suomi.fi Messages.

Your organisation can test the telecommunication connection by launching the SFTP client and connecting to the integration testing or production environment of the VIA service. After a successful identification, the materials directory appears on the screen. You can then try to transfer the material over SFTP (SFTP:put) to directory <home directory>/to_viestit/ipost/<palvelutunnus>.

The SFTP address of the VIA service in the integration testing environment (QA):

qat.integraatiopalvelu.fi (from the internet)
qat.integraatiopalvelu.vyv.fi (from the VY network).

The SFTP address of the VIA service in the production environment (PROD):

pr0.integraatiopalvelu.fi (from the internet)
pr0.integraatiopalvelu.vyv.fi (from the VY network).

Picture 1 is a sequence chart which shows the path of the messages in Suomi.fi Messages from your organisation to the end user. The operators, operations and messages are described in further detail below the picture.

1. Path of the messages in Suomi.fi Messages from the client organisation to the end user.

Operators and operations in the sequence chart

The operators and operations seen in Picture 1 are described below.

Client organisation

The client organisation is an authority that sends messages and other materials to end users, i.e. persons and companies. The messages and materials are sent from the client organisation’s system.

End user (person/company)

An end user is a person or a company that receives the messages and other materials sent by the client organisation, either in an electronic format into their mailbox in Suomi.fi Messages or as paper mail into their physical mailbox.

Perform a virus check

The background services of Suomi.fi Messages perform a virus scan on the materials.

Process the data

The background services of Suomi.fi Messages process the materials for each end user.

VIA, FTP server

The FTP server of the Shared Integration Platform (VIA) to which the client organisation sends the materials to be transmitted.

Suomi.fi Messages, background services

The background services of Suomi.fi Messages include mailing and storage services and the processing logic of the end users’ electronic mailboxes.

The printing service provider’s system

The printing service provider is responsible for printing, enveloping and mailing messages.

Suomi.fi Messages, mailbox

The end user can read the messages that have arrived into their electronic mailbox in Suomi.fi Messages. The end user can use Suomi.fi Messages via the Suomi.fi Web Service or Suomi.fi mobile application.

Messages in the sequence chart

The messages of Picture 1 are described in further detail below.

Message: Transfer materials
Return value: void
Explanation: Your organisation transfers the materials as an SFTP transfer to VIA’s FTP service.

Message: Transfer materials
Return value: void
Explanation: VIA forwards the material to the background services of Suomi.fi Messages.

Message: An acknowledgement of the receipt of electronic messages
Return value: void
Explanation: If your organisation has adopted the Return Channel, Suomi.fi Messages can send delivery receipts to your organisation of all electronic messages delivered. The receipts are sent through a return channel, if it has been taken into use via another interface.

Message: Send a message
Return value: void
Explanation: The end user is sent a notification about a new message.

Message: Read a message
Return value: void
Explanation: The end user logs into Suomi.fi Messages, navigates to their electronic mailbox and reads the message and the associated files.

Message: Retrieve a message and other materials
Return value: void
Explanation: The message and its attachments are retrieved into the electronic mailbox located the Suomi.fi Web Service’s Messages section from the background services of Suomi.fi Messages.

Message: Retrieve materials
Return value: void
Explanation: The printing service provider retrieves the materials for printing for end users who do not use Suomi.fi Messages.

Message: Deliver a letter
Return value: void
Explanation: If the end user does not use Suomi.fi Messages, the content of the message is sent to the end user by paper mail.

Updated: 17/3/2025

Digitalise your service path

Enhance information management

Improve service quality

Protect your data

Open, share and utilise data

Enhance information management

Protect your data

Develop responsibly

Open, share and utilise data

SFTP API

Are you satisfied with the content on this page?