Sending and receiving messages

sedex messaging involves sending and receiving messages. The Messaging REST API provides a set of operations to support both and this section describes the operations typically involved in each.

• Operations for sending sedex messages
• Operations for receiving sedex messages

SwaggerUI provides a detailed description of each operation, its parameters, request body, normal as well as error responses, and how the operation can be executed with curl.

Resources and objects describes the resources and objects used when calling the Messaging REST API operations.

Sending a sedex message

Use the following steps to send a sedex message:

1. Register a message.

   Operation: POST send/messages/register

   The envelope of a message must be registered.

   The response includes:

   • message-authorisation-result: Indicates whether the message may be sent to the recipients. If the message may be sent to all recipient, only an overall status is returned. If the message may not be sent to one or more of the recipients, a per-recipient status is also returned.
   • unique-sedex-message-id: (USMID) Is used to uniquely identify the message in later operations.

2. Upload the payload.

   Operation: POST send/messages/{unsique-sedex-message-id}/payload

   After the envelope has been registered, the payload can be uploaded. The USMID from the registration associates the payload with the envelope.

   The response indicates whether the upload was successful. If it was not successful, the response will include the reason.

3. Check the status of a sent message.

   Operation: GET send/messages/{unsique-sedex-message-id}/status

   Any time after a successful registration, the status of the message can be checked.

   The response includes:

   • The contents of the original envelope
   • The payload size
   • The current overall status of the message
   • The current status of the message with regard to each recipient

4. Get unacknowledged receipts for all sent messages.

   Operation: GET send/receipts

   The sedex platform generates a receipt for each recipient of a sedex message. Each receipt indicates the final status of a sedex Message with regard to one recipient: Was it successfully delivered to the recipient or did an error prevent delivery? The business application must regularly check for new unprocessed receipts, process them, and then acknowledged them.

   Note: Each call returns only the 200 currently oldest unacknowledged receipts. This is to keep receipts from being ignored or orphaned.

   The response includes:

   • The USMID of the particular message
   • The sedex ID of one recipient
   • A status code and the description of the status
   • The type of messaging interface used to send the message, e.g. file, web-service
   • Some of the information from the envelope

5. Acknowledge that a receipt has been processed by the sending business application.

   Operation: PUT send/receipts/acknowledge

   One or more receipts that have been processed by the business application which sent the message can be marked as such and will no longer occur in the list of unacknowledged receipts. Acknowledging a receipt completes the sending process.

   The response includes:

   • The total number of receipts that were acknowledged successfully or whose acknowledgement failed
   • The status of the acknowledgement for each receipt in the request

Optional sending operation

• Check if a message would be allowed to be sent.

  Operation: POST messages/pre-check

  Check whether the message represented by the envelope would be allowed to be sent. While the authorization check is identical to the register operation, nothing is stored and no USMID is returned.

Receiving a sedex Message

Use the following steps to receive a sedex message:

1. Request a list of incoming envelopes.

   Operation: GET receive/messages/envelopes

   The list of incoming message envelopes should be requested periodically. If there are no incoming messages, the response will be empty; there is no special response code for this case.

   Important: From a security standpoint, the business application should use the contents of the envelope to determine whether it is expecting the given message or not. If it is, the message should be processed, otherwise it should be deleted using the delete operation.

   The response includes:

   • A list of incoming message envelopes
   • Metadata relevant to the response, such as whether there are more envelopes to receive, pagination information, and any filter criteria applied to the request

2. Download the payload.

   Operation: GET receive/message/{unsique-sedex-message-id}/payload

   Download the payload associated with the USMID and use the contents for the corresponding business purposes.

   The X-payload-name HTTP header of the response contains the name of the file containing the payload.

3. Delete the received message.

   Operation: DELETE receive/message/{unsique-sedex-message-id}

   Messages that have been processed should be deleted by the business application.

   Deleting a message completes the receiving process and keeps the message's envelope from appearing in the list of incoming envelopes.

Optional receiving operations

• Request a list of the USMIDs of the incoming messages.

  Operation: GET receive/messages

  Depending on the business application's processing strategy, a list containing only the USMIDs of incoming messages can be requested. If there are no incoming messages, the response will be empty; there is no special response code for this case.

  Important: From a security standpoint, the business application should use the contents of the envelope to determine whether it is expecting and should process a given message or not; a USMID alone cannot indicate that.

  The response includes:

  • A list of USMIDs of the incoming messages
  • Metadata relevant to the response, such as whether there are more USMIDs to receive, pagination information, and any filter criteria applied to the request

• Get the envelope of a specific incoming message.

  Operation: receive/message/{unsique-sedex-message-id}/envelope

  Get the envelope matching the USMID.

  The response includes:

  • The envelope of the incoming message