1 of 11

1.0 Messaging

Developed by Rainer Türner (Information System Authority of Estonia), Magnus Hult (Element.io), John Cordeiro and Martin Karner (Estonian ICT Cluster), Bramhanand Jha (India's National e-Governance Division)

1 Version History

The version history table describes the major changes to the specifications between published versions.

Version

Authors

Comment

2 Description

This section provides context for this Building Block.

The Messaging Building Block provides a standardized, secure communication channel between GovStack service providers and end customers (in most cases citizens). By using GovStack Messaging Building Block, service providers rely on the building block's central functionalities, logging, back upping, security features, etc. without the need to reproduce and maintain them by themselves.

For greenfield developments, it helps developers build communication components on top of different GovStack services, to make use of federated architecture when passing messages, including machine- and human-triggered (both synchronous and asynchronous) ones.
Messaging Building Block is a standalone messaging gateway/client/proxy (including all possible modalities: email, SMS, etc.), but can also facilitate connections with existing messaging service providers, hence making the adoption process less disruptive for end users.

This Building Block can be used for messaging events in many different applications and use cases, such as:

Example A, encrypted: after being enrolled into a Health Care Program for the mothers of a newborn child, a woman/caretaker receives a message from the Health Care Service Provider about a doctor's appointment. The message is routed to an existing communication channel/application, in use and provided by the mother.
Example B, unencrypted: a reminder/notification message from the service provider to the mother about the same appointment. If a doctor decides to hold the consultation remotely, a link is sent to the mother and a video consultation is started (the conference is started and users join the room). The event is triggered by the Scheduler Building Block component and a new message is processed to the client.
Example C: a user-initiated message regarding a doctor consultation, targeted to a Health Care Provider's phone number or a chatbot URL (universal or targeted messaging back to the system).

Examples of Messaging Building Block

Messaging Building Block is enabling signing up for and receiving services, such as:

mother and childcare;
social care;
receiving entitlements from the government;
opening bank accounts;
communicating disaster messages or reminders about the voters' rights during elections;
etc.

The use cases are detailed in the section of the following document: ANNEX I - Use Case Tables.

3 Terminology

Terminology used within this specification.

Term

Description

4 Key Digital Functionalities

Key Digital Functionalities describe the core (required) functions that this Building Block must be able to perform.

The Messaging Building Block is a standalone messaging gateway/client/proxy (including all possible modalities: email, SMS, etc.) but can also facilitate connections with existing messaging service providers by enabling safe communication. The communication in this Building Block can be categorized in two different directions as follows:

4.1 Government to person (G2P)

informing End clients about their registration;
reminding and requesting End clients' confirmation for appointment booking or other events;
delivering information at scale to End clients;
alerting End clients in emergency contexts.

4.2 Person to Government (P2G)

providing data to the government/service;
getting confirmation about government services and interactions quickly;
asking for information about government services.

Communication between different government services (government to government) is out of the scope of this Building Block but can be enabled through the Information Mediator Building Block.

4.3 Out-of-Scope Assumptions

Scheduling messages according to some business logic is out of the scope of this Building Block because is done by Scheduler Building Block.
Processing of incoming message content to apply some business logic.
Fully offline and no internet connection scenarios.
Real-time video and audio conferencing.

5 Cross-Cutting Requirements

This section will highlight important requirements or describe any additional cross-cutting requirements that apply to this Building Block.

The cross-cutting requirements described in this section are an extension of the cross-cutting requirements defined in the architecture specification document. Any implementation MUST adhere to all requirements from GovStack Security Requirements.

5.1 Use de-normalized databases (REQUIRED)

There are two main reasons for using denormalized databases instead of traditional normalized databases. First, to significantly improve the performance of read queries. This is highly important as databases of the Messaging Building Block will be under a heavy load of requests that in many cases are expected to respond near real-time. Second, to be able to export the content of databases in the format of time-series databases (see below for its reasons). To achieve this, using "UPDATE" and "DELETE" queries in SQL commands SHOULD be disabled. If not, they MUST be avoided by developers and caught by automated tests if still used.

5.2 Archive Content of production-level databases continuously (RECOMMENDED)

By having this capability, it is possible to delete the content of processed data from production-level server databases right after they have been securely archived. This is important to reduce the impact of potential data breaches by security incidents of potentially N number of application servers hosted by different parties.

5.3 Time-series databases should be convertible to ready-to-use relational databases and vice versa (RECOMMENDED)

If done so, using archived datasets, either fully or partially, allows to recover and/or re-engineer lost databases (or just datasets of interest) automatically and in a matter of seconds if such pipelines have been predefined. Also, by converting the content of relational databases into a format of time-series databases, these purely text-based datasets are easily usable by different kinds of databases, analytics tools, etc., not just by the relational database used at first.

5.4 Enable message replication (RECOMMENDED)

In order to prevent single points of failure, messages must be replicated on at least 2 different service providers. In case of message replication, all unprocessed replicated messages must be kept track of and relevantly updated in order to prevent re-processing them.

5.5 Support policy configuration (REQUIRED)

Admin of the room must be able to choose the policy profile with the configuration of the message provider, e.g. retrial frequency.

5.6 Support queuing mechanism (REQUIRED)

Unsent and unsuccessfully delivered messages must remain in a queue until being successfully delivered or otherwise permanently processed.

Messages Delivery Statuses

Pending (initial state for all messages waiting to be queued); Queued (messages that are in the queue to be sent); Sent (messages with proper confirmation that was sent to the provider); Delivered (messages with proper confirmation that was delivered to the end-user); Errored (messages with error during delivery); Failed (messages that are errored and we gave up sending).

Delivery business rules

Messages not delivered in a period of 24 hours (any errored or queued messages more than 24 hours old must be labelled as failed and go out of the queue); Messages retrial (Errored messages must be retried for 24 hours).

5.7 Implement using stateless and horizontally scalable components (REQUIRED)

Technical components (with the exception of relational databases) must be stateless in the sense of the Service statelessness principle.

5.8 Implement horizontally scalable Databases (RECOMMENDED)

At least on the level of active-passive nodes based on the principle of "eventually consistent". Pending: initial state for all messages waiting to be queued.

Queued: messages that are in the queue to be sent.

Sent: messages with proper confirmation that was sent to the provider.

Delivered: messages with proper confirmation that was delivered to the end-user.

Errored: messages with an error during delivery.

Failed: messages that are errored and we gave up sending.

5.9 Messaging as a service must be vendor-neutral (REQUIRED)

If Messaging Building Block protocols are followed, the technical stack used to provide messaging as a service is vendor-neutral, meaning that anyone is free to use technical solutions of their own choice.

5.10 Only allowed participants can join the network (REQUIRED)

Only allowed participants are allowed to provide and use the services of Messaging Building Block.

5.11 Do not store users' contacts and readable messages at Messaging Building Block (REQUIRED)

Messaging Building Block is a dumb messaging proxy that gets all of its relevant input from its clients. This also includes the names and contact information of all relevant participants. Such sensitive information may not exist in its raw and/or re-engineerable form nor in databases or logs.

5.12 Message content must be readable only by intended participants (REQUIRED)

Depending on the specific use case, this may mean end-to-end encryption or SNI routing.

5.13 Audit logs must be provided (REQUIRED)

Every instance of a service must generate audit logs containing information about all of its actions regarding timestamps, related parties, identifiers to operations performed, and HTTP response codes for any given action. Audit logs may not contain the actual content of the message. Audit logs must be in a time series database format. Audit logs must be accessible by a given endpoint by the central service provider only. Audit logs should be periodically removed from their original source after a defined period of time.

5.14 Secure API exposure (REQUIRED)

All APIs are exposed via secure socket connections (HTTPS).

5.15 Client application authorisation tokens (REQUIRED)

Client applications must send authorization tokens in the authorization header of the request to authenticate users and the API Management Gateway will verify whether the token is valid.

5.16 Input validation checks (REQUIRED)

Perform input validation checks to prevent oversized message attacks, SQL injection attacks as well as JSON and XML threats.

5.17 Access quotas (OPTIONAL)

Manage access quotas and throttling.

5.18 API calls (REQUIRED)

Logging of all API calls made.

5.19 API consumption (RECOMMENDED)

Allow API providers to limit the rate of consumption for all API users.

5.20 Standardized backend error messages (REQUIRED)

Transform backend error messages into standardized messages so that all error messages look similar; this also eliminates exposing the backend code structure.

5.21 Minimal data for requests (REQUIRED)

Contact address (email, phone number, etc.), the message type, the content of the message, and the initiating source’s unique transaction ID.

5.22 Messaging processing (REQUIRED)

Asynchronous messaging processing. OpenAPI specifications for calling this function; resource models and data structures, internal and external interfaces.

5.23 Stateless architecture (REQUIRED)

Stateless architecture.

5.24 Message broker tool (RECOMMENDED)

Message broker tool to enable performant queueing mechanisms such as RabbitMQApache/Kafka, or GRPC for data transfer speed purposes.

5.25 Unstructured DATABASES (REQUIRED)

Databases with unstructured data should be treated with Elasticsearch/Logstash.

5.26 Message broker tool (RECOMMENDED)

End users should be registered as Message queue clients/subscribers in the Messaging Building Block. Subscription is required to receive a message.

6 Functional Requirements

This section lists the technical capabilities of this Building Block.

6.1 Government to person (G2P)

6.1.1 Queuing

The queuing process varies according to the policy and message type attached to the messaging, if an emergency messaging type applies to it, the messaging gets prioritized, otherwise, the FIFO algorithm (First In, First Out) applies to other message types. It saves all the requests for further processing, furthermore, works in the form of an "AS IS" process analysis without changing anything on the request. The message queueing mechanism will:

save a hash (MHASH) of the original request and a Unique Message ID (UMID);
respond with "Message received" to the sender with generated UMID.

6.1.2 Validation and Verification

Messaging requests go through a final check to be clean of defects and inconsistencies, to check with external systems as necessary:

check for message duplicates by making an actual request to a Time Series Database to see if entries with MHASH and UMID exist;
low-level validation of data types and data completeness;
check for inconsistencies;
standard error messages and codes are used as a response to inconsistent requests.

6.1.3 Workflow and Scheduling

In relation to batch logic, messages are scheduled against the availability of systems, throughput limitations, and rules set by programs.
Regular and repeat messages are scheduled.
Batches may be given prioritization in the queue according to the message settings.
The essential control logic may be included here specific to the individual batch sending and resending.
Additional workflow checks as required, including resending failed transactions.

6.2 Person to Government (P2G)

6.2.1 Messaging request initiation

Handles the initiation of input data processing from all the API messaging calls and makes the API access control verification from other Building Blocks to the Messaging Building Block and vice versa as well as within the Messaging Building Block, it will:

use Identity and access management for authentication;
perform input validation checks to prevent oversized message attacks, SQL injection attacks as well as JSON and XML threats;
require authentication for all API users;
manage access quotas and throttling;
logging of all API calls made;
allow API providers to limit the rate of consumption for all API users;
transform backend error messages into standardized messages so that all error messages look similar (this also eliminates exposing the backend code structure).

This request could come from two sources: external or internal. An external source could be another GovStack Building Block (e.g. the Registration Building Block). Either source must be appropriately authenticated and authorized to initiate the request. The request must contain at a minimum: the contact address (email, phone number, etc.), the message type, the content of the message, and the initiating source’s unique transaction ID.

6.2.2 Batch logic

Find unprocessed requests from a database.
Prepare each request for actual processing, requests may come as single or batch messages and every message needs to be treated as a separate entry.
It prepares unprocessed requests for actual processing.

6.2.3 Audit trails

Each component of the messaging building block should be capable of producing transaction logs. This is important to ensure that the system can be adequately monitored and troubleshooting can be performed efficiently and effectively.

The components should also generate transaction logs for events that capture at least the following information:

transaction date and time;
transaction source;
transaction destination;
supplementary data;
transaction status (success, failed, in progress).

The event logs and the transaction logs should NOT capture any sensitive data such as contact data, or channel authorization credentials.

Fetch and securely archive logs from working nodes is also expected.

6.2.4 Security layer

The security layer ensures that the content of messages and interactions with other Building Blocks are encrypted in transit. The security layer follows these requirements:

The communication must be TLS-secured using client authentication, Transport Layer Security protocol (TLS) 1.2 and above should be used to protect the confidentiality and integrity of the data in transit.
Personal profiles must never be disclosed to any unauthorized party.

Building Block Components

This section lists the technical capabilities of the Messaging Building Block. The following components are needed to achieve the technical functionalities of the messaging Building Block.

The Messaging Building Block is part of the GovStack implementation and is prompted to open up a two-way communication channel to deliver and capture messages/data between the GovStack systems and the end users, physical and legal persons.
As a rule, the Messaging Building Block does not own any information but is carrying the minimum amount of (meta) data needed to transfer/publish a message. Messaging Building Block allows other Building Blocks and applications to reach out to customers/citizens in order for them to be able to make a decision or access a service. This Building Block can also be used for broadcasting a disaster message.
Messaging policies are configurable modalities and channels that can be accessed/utilized through the Messaging Building Block in order to reach out to the users or groups. This Building Block is using existing applications/channels, such as e-mail, SMS, and messaging platforms for enabling users to subscribe to an application/channel provided by Messaging Building Block itself for text-based content.
Having published its messaging policies and services at the Information Mediator Building Block, the other Building Blocks and applications can discover and use the services of the Messaging Building Block.
Messaging Building Block allows for asynchronous communication, using either point-to-point communication or a Pub/Sub model (using Information Mediator Building Block) where the user is subscribed to a message room/group and will be receiving all messages intended for the “mother of newborn child” group.
Security: Before allowing any messages to be published, the Messaging Building Block fetches a corresponding ID and a role or a session token available for the user for authentication and access purposes. Incorporates privacy into its design when the purpose of the authentication is not revealed if a service provider sends an authentication request.

7 Data Structures

This section provides information on the core data structures/data models that are used by this Building Block.

7.1 Resource Model

The resource model shows the relationship between data objects that are used by this Building Block.

7.2 Data Structures

7.2.1 Data Elements (Generic Example)

7.2.1.1 Person

Standards

The following standards are applicable to data structures in the Messaging Building Block:

all services are provided as REST API requests;
only Transport Layer Security (TLS) Server Name Indication (SNI) extension-compatible requests are allowed;
REST calls and responses use JSON as the only allowed data format.

Using ISO 8601 on dates and times is a MUST;
UTF-8 character encoding on text input is a MUST.

Model Schemas

Each model schema MUST have a corresponding JSON Schema (API definition file).

8 Service APIs

This section provides a reference for APIs that should be implemented by this Building Block.

This section provides a reference for APIs that should be implemented by this Building Block. The APIs defined here establish a blueprint for how the Building Block will interact with other Building Blocks. Additional APIs may be implemented by the Building Block, but the listed APIs define a minimal set of functionality that should be provided by any implementation of this Building Block.

The GovStack non-functional requirements document provides additional information on how 'adaptors' may be used to translate an existing API to the patterns described here. This section also provides guidance on how candidate products are tested and how GovStack validates a product's API against the API specifications defined here.

The tests for the Messaging Building Block can be found in this GitHub repository.

8.1 Government to person (G2P)

8.1.1 Sending emails

8.1.1.1 Sending single emails one by one

This API is designed to send out emails one by one.

Although an email can be sent to multiple recipients by using email, emailCC and emailBCC appropriately, this is still considered as sending a single email.

Sample user story

As a Doctor working in a hospital, I want to notify my patient about a confirmed registration so that the patient would know when to come for a visit.

API endpoint

8.1.1.2 Sending multiple (batch) emails at once

This API is designed to send out identical emails to multiple (batch) recipients at once.

Sample user story

As a Hospital I want to notify a specified group of my clients about the possibility to register to vacant time slots within a limited period of time so that the clients potentially needing it the most would have a guaranteed chance to get an appointment

API endpoint

8.2 Person to Government (P2G)

8.2.1 Responding to emails

This API is designed to accept responses to emails that have been previously sent out by using the Messaging Building Block. The protocol itself is lightweight and expects custom services from anyone using it. The Messaging Building Block is responsible for delivering the message and does not know (or want to know) anything about the content of it, how it will be used, etc.

Sample user story

As a Hospital, I want to get and send responses from and to clients so that I could continue and keep track of email conversations taking place via GovStack

API endpoint

8.2.2 Reading the status of emails

This API is designed to provide information about the status of emails sent to the Messaging Building Block.

Sample user story

As a Doctor working in a hospital I want to know which emails I have sent haven't reached their destination so that I could contact such patients by using different means

API endpoint

Status of emails

Possible status of emails that can be queried are as follows:

scheduled
processing
deferred
bounced
not sent
delivered

There is no keeping track of emails which have been sent successfully, as this would end up creating and maintaining a massive database of emails, their senders and recipients, etc., which would be wrong for so many reasons.

9 Internal Workflows

This section provides a detailed view of how this Building Block will interact with other Building Blocks to support common use cases.

A workflow provides a detailed view of how this Building Block will interact with other Building Blocks to support common use cases.

This section lists workflows that this Building Block must support. Other workflows may be implemented in addition to those listed.

9.1 Workflow diagram

9.1.1 Prerequisites and dependencies

The main prerequisite for Person-to-Building Block communication is that there is an existing Sender/Source Building Block with the following properties:

the relevant credentials and details about the Person/Citizen to be addressed with;
the content of the message and a reference to a communication channel (contact details) to be used;
additionally, the service discovery service at the Information Mediator Building Block needs to be active. Information Mediator Building Block publishes the list of available services of the Messaging Building Block to the source GovStack Building Block, i.e. Workflow.

A reference token should be carried throughout the communication session in order to save a point of reference for reverse communication back from the Person to the Building Block. In other words, the main prerequisite for Person-to-Building Block communication is the availability of a communication channel and a reference token.

9.1.1.1 Description

This generic workflow is used to transfer messages between GovStack Building Block and the end user, Person. Data is submitted from a GovStack Building Block front-end application. This workflow shows a connection to GovStack Building Block (such as a government Health System Application) to convey a message that is associated with a real person.

9.1.1.2 Interaction with Other Building Blocks

This workflow requires interaction with the Information Mediator Building Block and a source GovStack Building Block, for example, a Health Care Service Building Block or registry Building Block.

9.1.1.3 Sequence Diagram

The sequence diagram shows the flow of data between Building Blocks for this workflow.

Messaging: Government to Person (G2P)

Messaging: Person to Government (P2G)

9.2 Interactions

9.2.1 Government/BB to Person communication

9.2.2 Person to Government/Building Block communication

10 Other Resources

This section links to any external documents that may be relevant, such as standards documents or other descriptions of this Building Block that may be useful.

10.1 Key Decision Log

10.2 Future Considerations

ANNEX I - Use Case Tables and Component diagrams

Use case table - Birth Certificate to Children

Use case table - Appointment booking confirmation for health services

Use case table - Alert Message

Annex II User Journeys

User journey

Use case table

5 Cross-Cutting Requirements

This section will highlight important requirements or describe any additional cross-cutting requirements that apply to this Building Block.

5.1 Use de-normalized databases (REQUIRED)

5.2 Archive Content of production-level databases continuously (RECOMMENDED)

5.3 Time-series databases should be convertible to ready-to-use relational databases and vice versa (RECOMMENDED)

5.4 Enable message replication (RECOMMENDED)

5.5 Support policy configuration (REQUIRED)

Admin of the room must be able to choose the policy profile with the configuration of the message provider, e.g. retrial frequency.

5.6 Support queuing mechanism (REQUIRED)

Unsent and unsuccessfully delivered messages must remain in a queue until being successfully delivered or otherwise permanently processed.

Messages Delivery Statuses

Delivery business rules

5.7 Implement using stateless and horizontally scalable components (REQUIRED)

Technical components (with the exception of relational databases) must be stateless in the sense of the Service statelessness principle.

5.8 Implement horizontally scalable Databases (RECOMMENDED)

At least on the level of active-passive nodes based on the principle of "eventually consistent". Pending: initial state for all messages waiting to be queued.

Queued: messages that are in the queue to be sent.

Sent: messages with proper confirmation that was sent to the provider.

Delivered: messages with proper confirmation that was delivered to the end-user.

Errored: messages with an error during delivery.

Failed: messages that are errored and we gave up sending.

5.9 Messaging as a service must be vendor-neutral (REQUIRED)

5.10 Only allowed participants can join the network (REQUIRED)

Only allowed participants are allowed to provide and use the services of Messaging Building Block.

5.11 Do not store users' contacts and readable messages at Messaging Building Block (REQUIRED)

5.12 Message content must be readable only by intended participants (REQUIRED)

Depending on the specific use case, this may mean end-to-end encryption or SNI routing.

5.13 Audit logs must be provided (REQUIRED)

5.14 Secure API exposure (REQUIRED)

All APIs are exposed via secure socket connections (HTTPS).

5.15 Client application authorisation tokens (REQUIRED)

Client applications must send authorization tokens in the authorization header of the request to authenticate users and the API Management Gateway will verify whether the token is valid.

5.16 Input validation checks (REQUIRED)

Perform input validation checks to prevent oversized message attacks, SQL injection attacks as well as JSON and XML threats.

5.17 Access quotas (OPTIONAL)

Manage access quotas and throttling.

5.18 API calls (REQUIRED)

Logging of all API calls made.

5.19 API consumption (RECOMMENDED)

Allow API providers to limit the rate of consumption for all API users.

5.20 Standardized backend error messages (REQUIRED)

Transform backend error messages into standardized messages so that all error messages look similar; this also eliminates exposing the backend code structure.

5.21 Minimal data for requests (REQUIRED)

Contact address (email, phone number, etc.), the message type, the content of the message, and the initiating source’s unique transaction ID.

5.22 Messaging processing (REQUIRED)

Asynchronous messaging processing. OpenAPI specifications for calling this function; resource models and data structures, internal and external interfaces.

5.23 Stateless architecture (REQUIRED)

Stateless architecture.

5.24 Message broker tool (RECOMMENDED)

Message broker tool to enable performant queueing mechanisms such as RabbitMQApache/Kafka, or GRPC for data transfer speed purposes.

5.25 Unstructured DATABASES (REQUIRED)

Databases with unstructured data should be treated with Elasticsearch/Logstash.

5.26 Message broker tool (RECOMMENDED)

End users should be registered as Message queue clients/subscribers in the Messaging Building Block. Subscription is required to receive a message.

6 Functional Requirements

This section lists the technical capabilities of this Building Block.

6.1 Government to person (G2P)

6.1.1 Queuing

save a hash (MHASH) of the original request and a Unique Message ID (UMID);
respond with "Message received" to the sender with generated UMID.

6.1.2 Validation and Verification

Messaging requests go through a final check to be clean of defects and inconsistencies, to check with external systems as necessary:

check for message duplicates by making an actual request to a Time Series Database to see if entries with MHASH and UMID exist;
low-level validation of data types and data completeness;
check for inconsistencies;
standard error messages and codes are used as a response to inconsistent requests.

6.1.3 Workflow and Scheduling

In relation to batch logic, messages are scheduled against the availability of systems, throughput limitations, and rules set by programs.
Regular and repeat messages are scheduled.
Batches may be given prioritization in the queue according to the message settings.
The essential control logic may be included here specific to the individual batch sending and resending.
Additional workflow checks as required, including resending failed transactions.

6.2 Person to Government (P2G)

6.2.1 Messaging request initiation

use Identity and access management for authentication;
perform input validation checks to prevent oversized message attacks, SQL injection attacks as well as JSON and XML threats;
require authentication for all API users;
manage access quotas and throttling;
logging of all API calls made;
allow API providers to limit the rate of consumption for all API users;
transform backend error messages into standardized messages so that all error messages look similar (this also eliminates exposing the backend code structure).

6.2.2 Batch logic

Find unprocessed requests from a database.
Prepare each request for actual processing, requests may come as single or batch messages and every message needs to be treated as a separate entry.
It prepares unprocessed requests for actual processing.

6.2.3 Audit trails

The components should also generate transaction logs for events that capture at least the following information:

transaction date and time;
transaction source;
transaction destination;
supplementary data;
transaction status (success, failed, in progress).

The event logs and the transaction logs should NOT capture any sensitive data such as contact data, or channel authorization credentials.

Fetch and securely archive logs from working nodes is also expected.

6.2.4 Security layer

The security layer ensures that the content of messages and interactions with other Building Blocks are encrypted in transit. The security layer follows these requirements:

The communication must be TLS-secured using client authentication, Transport Layer Security protocol (TLS) 1.2 and above should be used to protect the confidentiality and integrity of the data in transit.
Personal profiles must never be disclosed to any unauthorized party.

Building Block Components

This section lists the technical capabilities of the Messaging Building Block. The following components are needed to achieve the technical functionalities of the messaging Building Block.

The Messaging Building Block is part of the GovStack implementation and is prompted to open up a two-way communication channel to deliver and capture messages/data between the GovStack systems and the end users, physical and legal persons.
As a rule, the Messaging Building Block does not own any information but is carrying the minimum amount of (meta) data needed to transfer/publish a message. Messaging Building Block allows other Building Blocks and applications to reach out to customers/citizens in order for them to be able to make a decision or access a service. This Building Block can also be used for broadcasting a disaster message.
Messaging policies are configurable modalities and channels that can be accessed/utilized through the Messaging Building Block in order to reach out to the users or groups. This Building Block is using existing applications/channels, such as e-mail, SMS, and messaging platforms for enabling users to subscribe to an application/channel provided by Messaging Building Block itself for text-based content.
Having published its messaging policies and services at the Information Mediator Building Block, the other Building Blocks and applications can discover and use the services of the Messaging Building Block.
Messaging Building Block allows for asynchronous communication, using either point-to-point communication or a Pub/Sub model (using Information Mediator Building Block) where the user is subscribed to a message room/group and will be receiving all messages intended for the “mother of newborn child” group.
Security: Before allowing any messages to be published, the Messaging Building Block fetches a corresponding ID and a role or a session token available for the user for authentication and access purposes. Incorporates privacy into its design when the purpose of the authentication is not revealed if a service provider sends an authentication request.

8 Service APIs

This section provides a reference for APIs that should be implemented by this Building Block.

The tests for the Messaging Building Block can be found in this GitHub repository.

8.1 Government to person (G2P)

8.1.1 Sending emails

8.1.1.1 Sending single emails one by one

This API is designed to send out emails one by one.

Although an email can be sent to multiple recipients by using email, emailCC and emailBCC appropriately, this is still considered as sending a single email.

Sample user story

As a Doctor working in a hospital, I want to notify my patient about a confirmed registration so that the patient would know when to come for a visit.

API endpoint

Send a single email

POST/send/email/single

Query parameters

body*email (object)

Email containing information about the recipient

callbackcallbackSender (object)

URIstring

Example: "https://example.com/callback/emails/requestUid"

senderInfosenderInfo (object)

organisationNamestring

Example: "Example Medical Insitution"

organisationRegNrstring

Example: "GOV1234567890"

onBehalfOfNamestring

Example: "Example Medical Insitution"

onBehalfOfRegNrstring

Example: "GOV1234567890"

emailstring

Example: "sender@example.com"

replyTostring

Example: "reply-to@example.com"

namestring

Example: "Example Doctor"

recipientInforecipientInfo (object)

emailstring

Example: "customer@example.com"

emailCCstring

Example: "customer-cc@example.com"

emailBCCstring

Example: "customer-bcc@example.com"

namestring

Example: "Example Customer"

emailContentemailContent (object)

encodingstring

Example: "UTF-8"

titlestring

Example: "Example Title Of An Email"

contentstring

Example: "Example Customer"

Header parameters

apiKey*string

Response

Request successfully accepted

Body

responsestring

Example: "Request successfully accepted. Use \\\"requestUid\\\" to track it's status."

requestUidstring

Example: "UfQK-CPju-Ea5B-6y7X-8A72-VqU5"

Request

Response

8.1.1.2 Sending multiple (batch) emails at once

This API is designed to send out identical emails to multiple (batch) recipients at once.

Sample user story

API endpoint

Send batch emails

When sending batch emails, recipients information is passed in base64 format. Sender information and email content must be the same for all recipients.

POST/send/email/batch

Query parameters

body*batchEmail (object)

Email containing information about the recipient

callbackURIcallbackSender (object)

URIstring

Example: "https://example.com/callback/emails/requestUid"

senderInfosenderInfo (object)

organisationNamestring

Example: "Example Medical Insitution"

organisationRegNrstring

Example: "GOV1234567890"

onBehalfOfNamestring

Example: "Example Medical Insitution"

onBehalfOfRegNrstring

Example: "GOV1234567890"

emailstring

Example: "sender@example.com"

replyTostring

Example: "reply-to@example.com"

namestring

Example: "Example Doctor"

recipientInfobatchRecipientInfo (object)

batchEmailAsBase64string (base64)

Example:

"W3sKCSJyZWNpcGllbnRJbmZvIjogewoJCSJlbWFpbCI6ICJjdXN0b21lckBleGFtcGxlLmNvbSIsCgkJImVtYWlsQ0MiOiAiY3VzdG9tZXItY2NAZXhhbXBsZS5jb20iLAoJCSJlbWFpbEJDQyI6ICJjdXN0b21lci1iY2NAZXhhbXBsZS5jb20iLAoJCSJuYW1lIjogIkV4YW1wbGUgQ3VzdG9tZXIiCgl9Cn0sIHsKCSJyZWNpcGllbnRJbmZvIjogewoJCSJlbWFpbCI6ICJkZWFyLWN1c3RvbWVyQGV4YW1wbGUuY29tIiwKCQkibmFtZSI6ICJVbmtub3duIEN1c3RvbWVyIgoJfQp9XQ=="

emailContentemailContent (object)

encodingstring

Example: "UTF-8"

titlestring

Example: "Example Title Of An Email"

contentstring

Example: "Example Customer"

Header parameters

apiKey*string

Body

string

Response

Request successfully accepted

Body

responsestring

Example: "Request successfully accepted. Use \\\"requestUid\\\" to track it's status."

requestUidstring

Example: "UfQK-CPju-Ea5B-6y7X-8A72-VqU5"

Request

Response

8.2 Person to Government (P2G)

8.2.1 Responding to emails

Sample user story

As a Hospital, I want to get and send responses from and to clients so that I could continue and keep track of email conversations taking place via GovStack

API endpoint

An optional custom service to provide an endpoint for client-specific functionality to accept replied emails, etc

This service may reside on both Messaging BB's and client's side. If used, a matching OpenAPI spec must be provided by the service provider, describing the expected input when making request to the endpoint.

POST/callback/email

Query parameters

body*callbackContent (object)

Email containing information about the recipient

metastring

Example: "Meta-info"

contentstring (bae64)

Example: "Q2xpZW50LXNwZWNpZmljIGNvbnRlbnQsIG1vc3QgbGlrZWx5IEpTT04="

Header parameters

apiKey*string

requestUid*string

Response

Request successfully accepted

Request

8.2.2 Reading the status of emails

This API is designed to provide information about the status of emails sent to the Messaging Building Block.

Sample user story

As a Doctor working in a hospital I want to know which emails I have sent haven't reached their destination so that I could contact such patients by using different means

API endpoint

Get an overview of sent emails statuses

Get status of sent emails. Use both "apiKey" and "requestUid" in your request.

GET/status/email

Query parameters

status*array of enum

Select status values to fetch data for

itemsenum

scheduledprocessingdeferredbouncednotSentdelivered

Header parameters

apiKey*string

requestUid*string

Response

Request successfully accepted

Body

scheduledinteger (int32)

Example: 0

processinginteger (int32)

Example: 1004

deferredinteger (int32)

Example: 0

bouncedinteger (int32)

Example: 257

notSentinteger (int32)

Example: 0

deliveredinteger (int32)

Example: 9032

Request

Response

Status of emails

Possible status of emails that can be queried are as follows:

scheduled
processing
deferred
bounced
not sent
delivered