REST API to Automate Message Workflows

MFT Gateway REST API is released! With the latest update 2.1.0, now you can automate your message workflows easily using REST API without depending on the MFT Gateway web console. Let’s take a quick look around what you can achieve with MFT Gateway REST API.

API Endpoints

First let’s take a quick overview of MFT Gateway REST API endpoints.

Base URL: https://api.mftgateway.com

Authentication

In order to access REST API endpoints, first you need to get your API access token by submitting your MFT Gateway user credentials to the Authorization endpoint. After successful authentication you will receive two JWT tokens,

• API Token: Authentication token which needs to be set in the Authorization header
• Refresh Token: You can use this token to refresh your API session via the Refresh Auth Token endpoint without submitting your credentials again.

Sending an AS2 Message

You can send AS2 messages without logging into the web console using the Send Message endpoint. Let’s take a quick look at how we can send a new AS2 message using the REST API.

First you need to set all required header information in your POST request.

• AS2-From: AS2 identifier of trading station from which you wish to send the message
• AS2-To: AS2 identifier of trading partner who is intended to receive the message
• Content-Type: Attachment content type (application/x12, text/plain, etc.)

There are two optional headers are supported in this endpoint

• Subject: Subject line for the AS2 message. If not specified, the REST API will add a default message subject “AS2 message from MFT Gateway REST API”.
• Attachment-Name You can specify the name of your uploaded file (attachment) in this header. If not specified, the file name defaults to “Attachment”.

After submitting a message send request, MFT Gateway will queue your message for sending once the processing has been completed. If your message is successfully processed you will receive the new message’s AS2 Identifier via a response body and the absolute URL to the AS2 message via Link response header.

Listing Messages

MFT Gateway has two main API endpoints for message listing. All the messages that you are receiving from your trading partners will be available in your inbox. Messages that are sent to trading partners can be fetched from the _ outbox_. List message API calls will return a list of corresponding message AS2 identifiers.

Sent Messages

MFT Gateway message sending life cycle has three main states. Once you submit a new message sending request, that message will enter the queued status. Messages will remain in queued status until the sending process is completed. Apart from such initial sending (first-time) messages, automatically and manually retried messages will also be moved into the queued status. You can list your queued messages via the List Queued Messages endpoint.

After the send, depending on the HTTP response, the message will enter either one of two states. If MFT Gateway got a successful (e.g. HTTP 200) response, the message will enter sent status which will be the end of its lifecycle. You can fetch such messages via the List Sent Messages endpoint.

Sometimes things do not work the way we expected. Your trading partner’s message receiving endpoint might not be reachable or things might go wrong in your partner’s end. Whatever the reason was, if MFT Gateway receives an unsuccessful response from your trading partner, the message will enter either one of the following states, depending on the nature of the response.

If the HTTP response contains a status code indicating that it is safe to trigger the retrying process without user interaction, MFT Gateway will move the message back to the queued status, and start an automatic message retrying process. Otherwise the message will be moved on to failed status, ending the message lifecycle. List Failed Messages endpoint can be used to fetch such failed messages.

Received Messages

Unlike message sending, MFT Gateway message receiving lifecycle is very straightforward with only one status: ** received**. You can list your received messages from the List Received Messages endpoint.

Fetching a Message

Like in message listing endpoints, MFT Gateway REST API has two endpoints to fetch AS2 message details. Both endpoints accept an AS2 message identifier as a path parameter - which you can pick from the list returned in the listing API response.

You can use the Retrieve Inbox (Received) Message endpoint to fetch a particular message received from your trading partner.

Unlike in message listing endpoints, there is a unified endpoint for retrieving a sent message, regardless of its current status: Retrieve Outbox (Sent/Queued/Failed) Message.

Endpoint response will be a JSON containing message details. This response can be categorized into three main parts. Top level of the response contains basic details about the message: AS2 message identifier, sender, receiver, etc. Then message transport headers are available in the transportHeaders field. Finally, if the intended message contains an MDN (Message Disposition Notification), it’s details will be available in the mdnMessage field.

Downloading Attachments

MFT Gateway REST API content downloading endpoints (attachments/MDN) will deliver you a pre-signed URL which can be used to directly download your content by making a HTTP GET request. An important thing to remember is that the validity of those pre-signed URLs is limited to ten minutes; you might have to re-request the URLs if they are not used before expiring.

REST API has two endpoints, Retrieve Inbox (Received) Message Attachment(s) and Retrieve Outbox (Sent/Queued/Failed) Message Attachment(s), to download message attachments. Depending on whether the intended message is an inbox (received) or an outbox (sent) message, you can use the relevant endpoint for downloading attachments.

Here is a sample response:

{
 "total": 1,
  "attachments": [
    {
      "name": "Attachment.raw",
      "url": "https://short-lived-url-to-download-attachment"
  }

Downloading MDNs

You can use the Retrieve Inbox (Received) Message MDN endpoint to download a sent MDN for a received message. To download received MDN from a trading partner for a message that has been sent by you, you can use the Retrieve Outbox (Sent) Message MDN endpoint. Both endpoints accept the AS2 identifier of the parent message, as a path parameter. Just like in downloading message attachments, these endpoint responses contain pre-signed URLs to download the actual raw MDN content.

Here is a sample response:

{
  "url": "https://short-lived-url-to-download-mdn"
}

So those are the main endpoints available in the MFT Gateway REST API initial release and now you know what you can do with the REST API. One final thing to remember, the initial release of the API endpoint only supports sending a single attachment (file) per message - but we are already working on multiple attachment support, and it will be available very soon.

Sign Up for 30 day Free Trial! Stay tuned for more updates!

Lahiru Ananda

Lahiru is a Software Architect at Aayu Technologies, bringing over 5 years of experience in the enterprise software industry, B2B communication, and cloud technologies. As the lead architect and designer of the MFT Gateway, he has been involved in the development and maintenance of various Aayu products. Outside of work, he enjoys the strategic challenges of chess and relaxing with movies and TV shows.