Technical deployment

First read the introduction of the service on the Service description page. The functionalities provided in the service are discussed in the Functionalities section. On the Technical description page, you can read about how Suomi.fi Messages works in practice and what interface options there are for using Suomi.fi Messages.

In addition to general familiarisation, your organisation must ensure that the technical preconditions for using Suomi.fi Messages are met. Take into account at least the following matters:

• Suomi.fi Messages does not have a user interface for organisations. User interfaces for the service are only offered to end users.
• Your organisation or the provider you have selected must have a system that is capable of sending messages.
• Your integration must be implemented in a secure manner. The REST interface uses secure encryption algorithms according to the TLS protocol, which must be supported by the systems you use. In the future, we will require support for TLS 1.3 encryption. We recommend enabling TLS 1.3 support in your systems already now.
• To be able to send an electronic message, your organisation must have at least the recipient’s personal identity code or business ID, which is used to allocate the message to the correct electronic mailbox.
• When sending paper mail, your organisation must have at least the recipient's address details because Suomi.fi Messages does not have an integration with a register containing address data from the Population or Business Information System.
• Authentication of REST requests is performed with an authentication token, which can be obtained from the REST interface with your organization’s credentials (username and password). The temporary password assigned to your organization must be changed before using the REST interface. We recommend automating this password change as part of a regular process. The authentication token has a limited validity period and must be refreshed when needed.

Possible contacts with the Digital and Population Data Services Agency (DVV) are handled as part of the administrative deployment process. If necessary, participate in the meetings concerning the deployment together with the persons responsible for the administration of the deployment.

Identify the current state of your systems and what changes or integrations are required in them to initiate the use of Suomi.fi Messages.

Support the persons responsible for the administration of the deployment in the preparation of the project.

Submit the technical information required for deployment

Provide the technical information required for deployment, such as IP addresses, in support of the Administrative deployment process.

During the administrative deployment phase, in step 3. Apply for an access licence and complete the service information form, your organisation provides the IP addresses to be used in the test and production environments. Based on this information, DVV will make the required IP whitelisting and configurations.

The use of Suomi.fi Messages is only possible from pre-approved IP addresses

Using the Suomi.fi Messages APIs requires that connections are established from IP addresses that have been submitted and approved in advance by your organisation. When deploying the service, your organisation must provide all public IP addresses from which its traffic is visible to the Suomi.fi Messages APIs.

If your organisation's traffic is routed through a NAT or proxy server, the IP address to be reported may not be the address of an individual workstation or server. In such cases, you must provide the public IP address that appears to the Suomi.fi Messages APIs as the source of the incoming connection.

Connections are only permitted from approved IP addresses. If you are unsure which IP address should be reported, consult your organisation's network specialist or system supplier.

Provide separate IP addresses for the test and production environments

The IP addresses used by the test and production environments must be reported separately. The test and production environments should be implemented as similarly as possible, so that the results observed during testing correspond closely to the production environment. However, the environments should remain separate wherever possible, even though in some cases they may use the same public IP address.

IP address ranges can also be approved when necessary

A single IP address is the preferred option. If your organisation uses multiple source addresses, for example in a development or test environment, a limited IP address range may be approved instead of several individual addresses.

For security reasons, any approved IP address range must be as narrow as possible. Very large address ranges can generally not be approved.

The aim in both the test and production environments of Suomi.fi Messages is to limit approved IP addresses and IP ranges to those from which the service is actually used.

• For example, very large address ranges at the /16 level are generally not permitted.

DVV enables access for the submitted IP addresses

After the required forms have been submitted, DVV will enable access for the IP addresses provided by your organisation in both the test and production environments.

The address of the test environment is api.messages-qa.suomi.fi and the instructions for using it are described in the interface documentation of the test environment (api.messages-qa.suomi.fi)Opens in a new window..

The address of the production environment is api.messages.suomi.fi and the instructions for using it are described in the interface documentation of the production environment (api.messages.suomi.fiOpens in a new window.).

You will receive the required credentials

After the IP whitelisting and configurations have been completed, DVV will send your organisation the following information by encrypted email: test personal identity codes, system ID (systemId), service ID (serviceId), and temporary password for the test environment.

Start using the test environment

First, change the temporary password you received to a password chosen by your organisation and then verify that the credentials work correctly.

Change the temporary password as follows:

1. Authenticate yourselves in the token endpoint of the test environment by using the identifiers you received. The address of the endpoint is api.messages-qa.suomi.fi/v1/token. The username is the system ID you received and the password is the temporary password you received.
2. The endpoint returns an authentication token to you.
3. Change the temporary password into your desired password in the change-password endpoint with the authentication token you received in step 2. The address of the endpoint is api.messages-qa.suomi.fi/v1/change-password.
4. Store the password you have chosen securely.

To test the functioning of the password you have set, follow these steps:

1. Authenticate yourselves in the token endpoint of the QA environment. The address of the endpoint is api.messages-qa.suomi.fi/v1/token. The username is the system ID you received and the password is the temporary password you have chosen.
2. The endpoint returns an authentication token to you.
3. Use the authentication token you received to call some other endpoint in the QA environment. For example, the endpoint events returns code 200 if the identifiers work.

You can now start building and testing your integration in the test environment.

Please note that all API endpoints require an authentication token obtained as described above, both in the test and production environments.

If your organisation wants to deploy the printing, enveloping and distribution service (TKJ service), see step 3 on the Administrative deployment page and the Deployment of the printing, enveloping and distribution service page. The TKJ service provider, Posti Messaging Oy, will send the credentials required for paper mail delivery to your organisation by post.

The actual technical development will now take place.

Implement the possible integrations or changes to your own service system according to the specifications drawn up by your organisation. If you join through standard software, take care of the implementation together with the producer of the software concerned. Familiarise yourself with the technical descriptions in the Interface documentation of the test environment (api.messages-qa.suomi.fi)Opens in a new window..

We recommend that you implement the changes one interface at a time and already test the implementation in connection with the development. You should also take into account possible network errors and momentary interruptions so that you keep sending the message for a sufficient number of times and for long enough.

In the testing phase, it is ensured that Suomi.fi Messages as a whole works as it should when you use it. Your organisation must test all the test cases that are essential for its connection as well as their different stages.

The instructions for the different test cases have been compiled on the page Testing instructions. Testing is carried out by using the test personal identity codes delivered to your organisation by DVV.

Please note that material containing personal data or confidential information must not be sent to the test environment. The test environment is shared by all.

If you conduct performance testing with a larger volume and need a larger number of test personal identity codes or business IDs, contact viestit-kayttoonotot@dvv.fi.

If you use standard software, discuss the required extent of testing with your provider. Your organisation is responsible for ensuring appropriate testing of the connection.

Support the administrative deployment process in completing the deployment checklist. Review the checklist carefully to ensure that all essential deployment tasks have been completed.

The checklist is available in step 6 of the Administrative Deployment page. Return the completed checklist and proceed to production use.

After reviewing the checklist submitted by your organisation, DVV will send the production environment password to the email address specified in the checklist.

The password must be changed using the change-password endpoint.

• The system ID (systemId) and service ID (serviceId) that you received earlier will also remain valid in the production environment.

The address of the production environment is api.messages.suomi.fi. Its descriptions have been compiled in the Interface documentation in the production environment (api.messages.suomi.fi)Opens in a new window..

Verify the functionality of the entire service chain in the production environment using real data. Test personal identity codes can no longer be used in the production environment, so limit production testing to what is necessary to verify that the service works as expected.

The technical deployment of Suomi.fi Messages is now complete.

You can now start using the service in the production environment.

The technical work required for using Suomi.fi Messages does not end with the deployment. Your organisation must also take care of the technical maintenance of the connection during its entire life cycle.

We recommend that your organization changes the REST interface password at least every six months, preferably more often. Your organisation should automate its password rotation process. Read further instructions on the Technical maintenance page.