Dispatch

All Sections

How it Works

Content

Scheduling messages

Messages can be scheduled using either the Dispatch API, or in the MolnX portal. A message payload is any JSON-embeddable UTF-8 string of up to 60 KiB characters.

Messages are scheduled to be delivered to targets. A target can be one of several supported types. The currently supported target types are webhooks, Amazon SQS and Amazon SNS.

Below is an example showing how to use the Dispatch API to schedule a short message using cURL.

$ curl -X POST https://api.dispatch.molnx.com/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKENAn OAuth 2 access token
" \
  -d '
{
  "targetId": "DI-T-aabbcc1122The ID of the target the message will be delivered to.
",
  "deliveryTime": "2020-07-01T12:34:00ZAn ISO 8601 compatible date and time string.
",
  "payload": "Hello, World!The payload may be any JSON embeddable string
"
}
'

Enabling and disabling targets

Dispatch will continually check if there are any undelivered messages to be delivered for each of your configured and enabled targets. This check is performed roughly every minute. Depending on the exact scheduled delivery time and the timing of the check, the actual delivery may be delayed by up to 2 minutes under normal circumstances.

The status of each message and any delivery attempts, both successful and failed, can be viewed in the Portal.

Message states

A message will always be in one of the following states:

Scheduled: The message has been scheduled but not yet delivered.
Delivered: The message has been delivered.
Cancelled: The message has been cancelled.
Dead Letter: The message has failed to be delivered enough times to be marked as a dead letter. A dead letter message may be rescheduled.

Data retention

A successfully delivered message is deleted after 24 hours.
A cancelled message is deleted after 24 hours.
Information on a failed delivery attempt is deleted after 7 days (168 hours).
Dead letter messages are deleted after 7 days (168 hours).

Retry policy

A message is immediately retried once upon an retryable delivery failure.
If the retry fails, the message is rescheduled for delivery 1 minute later.
If the message has not been delivered after 5 such 1 minute delays, the message is rescheduled for delivery 1 hour later.
If the message has not been delivered after 24 such 1 hour delays, the message is marked as a Dead Letter.

In total, 2 * 5 * 24 = 240 deliveries over roughly 24 hours are attempted before the message is marked as a dead letter.

Any not yet delivered message, including a dead letter, can be rescheduled manually in the Portal or using the Dispatch API. Rescheduling a message will reset the retry-flow.

A non-retryable failure immediately causes the message to be marked as a Dead Letter.

Retryable and non-retryable delivery failures

What failures are regarded as retryable or not retryable will depend on the target type. For example, a 400 status code returned from a webhook is regarded as a non-retryable failure and will immediately cause the message to be marked as a dead letter. On the other hand, a 500 status code is regarded as retryable will be rescheduled according to the above retry policy.

You can find more detailed information on the documentation pages for each target type. TODO

Delivery formats

Below is an example of a message being delivered to a webhook:

POST /my-target-endpointThe URL path as configured in the target.
Content-Type: application/json
 
{
  "messageId": "DI-M-11111111-2222-3333-4444-555555555555The ID of the message being delivered.
",
  "targetId": "DI-T-aabbcc1122The ID of the target being delivered to.
",
  "originalDeliveryTime": "2020-07-01T12:34:00ZThe delivery time as specified in the scheduling request. An ISO 8601 date and time string.
",
  "deliveryTime": "2020-07-01T12:34:56ZThe actual time when the delivery was made. An ISO 8601 date and time string.
",
  "payload": "Hello, World!The payload as specified in the scheduling request
"
}

If you have any questions you can't find the answer for, please don't hesitate to contact us.