arrow-left

All pages
gitbookPowered by GitBook
1 of 1

Loading...

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 documentarrow-up-right 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.arrow-up-right

hashtag
8.1 Government to person (G2P)

hashtag
8.1.1 Sending emails

hashtag
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.

hashtag
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.

hashtag
API endpoint

hashtag
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.

hashtag
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

hashtag
API endpoint

hashtag
8.2 Person to Government (P2G)

hashtag
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.

hashtag
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

hashtag
API endpoint

hashtag
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.

hashtag
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

hashtag
API endpoint

hashtag
Status of emails

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

  1. scheduled

  2. processing

  3. deferred

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.

bounced

  • not sent

  • delivered

  • hashtag
    Send a single email

    post
    Authorizations
    Query parameters
    Header parameters
    apiKeystringRequired
    Responses
    chevron-right
    200

    Request successfully accepted

    application/json
    responsestringOptionalExample: Request successfully accepted. Use \"requestUid\" to track it's status.
    requestUidstringOptionalExample: UfQK-CPju-Ea5B-6y7X-8A72-VqU5
    chevron-right
    405

    Invalid input

    post
    /send/email/single

    hashtag
    Send batch emails

    post

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

    Authorizations
    Query parameters
    Header parameters
    apiKeystringRequired
    Body
    stringOptional
    Responses
    chevron-right
    200

    Request successfully accepted

    application/json
    responsestringOptionalExample: Request successfully accepted. Use \"requestUid\" to track it's status.
    requestUidstringOptionalExample: UfQK-CPju-Ea5B-6y7X-8A72-VqU5
    chevron-right
    405

    Invalid input

    post
    /send/email/batch

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

    post

    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.

    Authorizations
    Query parameters
    Header parameters
    apiKeystringRequired
    requestUidstringRequired
    Responses
    chevron-right
    200

    Request successfully accepted

    No content

    chevron-right
    405

    Invalid input

    post
    /callback/email

    No content

    hashtag
    Get an overview of sent emails statuses

    get

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

    Authorizations
    Query parameters
    Header parameters
    apiKeystringRequired
    requestUidstringRequired
    Responses
    chevron-right
    200

    Request successfully accepted

    application/json
    scheduledinteger 路 int32OptionalExample: 0
    processinginteger 路 int32OptionalExample: 1004
    deferredinteger 路 int32OptionalExample: 0
    bouncedinteger 路 int32OptionalExample: 257
    notSentinteger 路 int32OptionalExample: 0
    deliveredinteger 路 int32OptionalExample: 9032
    chevron-right
    405

    Invalid input

    get
    /status/email
    POST /send/email/single?body=[object+Object] HTTP/1.1
    apiKey: text
    Accept: */*
    
    {
      "response": "Request successfully accepted. Use \\\"requestUid\\\" to track it's status.",
      "requestUid": "UfQK-CPju-Ea5B-6y7X-8A72-VqU5"
    }
    POST /send/email/batch?body=[object+Object] HTTP/1.1
    apiKey: text
    Content-Type: application/json
    Accept: */*
    Content-Length: 6
    
    "text"
    {
      "response": "Request successfully accepted. Use \\\"requestUid\\\" to track it's status.",
      "requestUid": "UfQK-CPju-Ea5B-6y7X-8A72-VqU5"
    }
    POST /callback/email?body=[object+Object] HTTP/1.1
    apiKey: text
    requestUid: text
    Accept: */*
    
    GET /status/email?status=scheduled HTTP/1.1
    apiKey: text
    requestUid: text
    Accept: */*
    
    {
      "scheduled": 0,
      "processing": 1004,
      "deferred": 0,
      "bounced": 257,
      "notSent": 0,
      "delivered": 9032
    }