Cancel message

Cancel a message that is currently in the process of being delivered. A well-formatted API call to the cancel message API will return either 200 status code for a successful cancellation or 409 status code for an unsuccessful cancellation. Both cases will include the actual message record in the response body (see details below).

URL: https://api.courier.com/messages/:message_id/cancel

Method: POST

Path Parameters

message_idstringrequired

A unique identifier representing the message ID

Responses

status: 200 SUCCESS

eventstring

A unique identifier associated with the message.

idstring

A unique identifier associated with the message you wish to retrieve (results from a send).

statusstring

CLICKED
- The recipient has clicked on any link in the message at least one time.
DELIVERED
- The provider successfully delivered the message to the recipient.
ENQUEUED
- The request has been received to send a message, is waiting in the work queue.
OPENED
- The recipient has opened the message at least one time.
CANCELED
- The message has been canceled such that it will not be delivered.
SENT
- The message has been accepted by the provider.
UNDELIVERABLE
- The message could not be delivered to at least one provider, or the provider could not deliver the message to the recipient. This can happen for multiple reasons: an error, insufficient profile data, invalid notification setup, invalid integration configuration, etc.
UNMAPPED
- Could not find a corresponding notification or event for the messages.
UNROUTABLE
- The message could not be routed to any channel or provider. This can happen for multiple reasons: insufficient profile data, invalid notification setup, invalid integration configuration, etc.

recipientstring

A unique identifier associated with the message recipient.

canceledAtnumberrequired

A UTC timestamp at which Courier received the cancel request. This is stored as a millisecond representation of the Unix epoch (the time passed since January 1, 1970).

clickednumber

A UTC timestamp at which the recipient clicked on a tracked link for the first time. This is stored as a millisecond representation of the Unix epoch (the time passed since January 1, 1970).

deliverednumber

A UTC timestamp at which the Integration provider delivered the message. This is stored as a millisecond representation of the Unix epoch (the time passed since January 1, 1970).

enqueuednumber

A UTC timestamp at which Courier received the message request. This is stored as a millisecond representation of the Unix epoch (the time passed since January 1, 1970).

errorstring

A message describing the error that occurred.

jobIdstringrequired

A unique identifier associated with the processing of a bulk send job.

listIdstring

A unique identifier associated with the Courier List entity.

listMessageIdstring

A unique identifier associated with the request id from a list send request.

notificationstring

A unique identifier associated with the notification of the delivered message.

openednumber

A UTC timestamp at which the recipient opened a message for the first time. This is stored as a millisecond representation of the Unix epoch (the time passed since January 1, 1970).

runIdstring

A unique identifier associated with the automation run.

sentnumber

A UTC timestamp at which Courier passed the message to the Integration provider. This is stored as a millisecond representation of the Unix epoch (the time passed since January 1, 1970).

status: 409 FAILURE

eventstring

A unique identifier associated with the message.

idstring

A unique identifier associated with the message you wish to retrieve (results from a send).

statusstring

CLICKED
- The recipient has clicked on any link in the message at least one time.
DELIVERED
- The provider successfully delivered the message to the recipient.
ENQUEUED
- The request has been received to send a message, is waiting in the work queue.
OPENED
- The recipient has opened the message at least one time.
CANCELED
- The message has been canceled such that it will not be delivered.
SENT
- The message has been accepted by the provider.
UNDELIVERABLE
- The message could not be delivered to at least one provider, or the provider could not deliver the message to the recipient. This can happen for multiple reasons: an error, insufficient profile data, invalid notification setup, invalid integration configuration, etc.
UNMAPPED
- Could not find a corresponding notification or event for the messages.
UNROUTABLE
- The message could not be routed to any channel or provider. This can happen for multiple reasons: insufficient profile data, invalid notification setup, invalid integration configuration, etc.

recipientstring

A unique identifier associated with the message recipient.

canceledAtnumberrequired

A UTC timestamp at which Courier received the cancel request. This is stored as a millisecond representation of the Unix epoch (the time passed since January 1, 1970).

clickednumber

A UTC timestamp at which the recipient clicked on a tracked link for the first time. This is stored as a millisecond representation of the Unix epoch (the time passed since January 1, 1970).

deliverednumber

A UTC timestamp at which the Integration provider delivered the message. This is stored as a millisecond representation of the Unix epoch (the time passed since January 1, 1970).

enqueuednumber

A UTC timestamp at which Courier received the message request. This is stored as a millisecond representation of the Unix epoch (the time passed since January 1, 1970).

errorstring

A message describing the error that occurred.

jobIdstringrequired

A unique identifier associated with the processing of a bulk send job.

listIdstring

A unique identifier associated with the Courier List entity.

listMessageIdstring

A unique identifier associated with the request id from a list send request.

notificationstring

A unique identifier associated with the notification of the delivered message.

openednumber

A UTC timestamp at which the recipient opened a message for the first time. This is stored as a millisecond representation of the Unix epoch (the time passed since January 1, 1970).

runIdstring

A unique identifier associated with the automation run.

sentnumber

A UTC timestamp at which Courier passed the message to the Integration provider. This is stored as a millisecond representation of the Unix epoch (the time passed since January 1, 1970).

Request Example

curl --request POST \
     --url https://api.courier.com/messages/1-61e9dd53-b5bb6c863b7ffbe83ad4b28d/cancel \
     --header 'Accept: application/json' 

// Dependencies to install:
// $ npm install node-fetch --save

const fetch = require('node-fetch');

const options = {
  method: 'POST',
  headers: {
    Accept: 'application/json'
  },
};

fetch('https://api.courier.com/messages/1-61e9dd53-b5bb6c863b7ffbe83ad4b28d/cancel', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://api.courier.com/messages/1-61e9dd53-b5bb6c863b7ffbe83ad4b28d/cancel")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'application/json'

response = http.request(request)
puts response.read_body

# Dependencies to install:
# $ python -m pip install requests

import requests

url = "https://api.courier.com/messages/1-61e9dd53-b5bb6c863b7ffbe83ad4b28d/cancel"

headers = {
  "Accept": "application/json"
}

response = requests.request("POST", url, headers=headers)

print(response.text)

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://api.courier.com/messages/1-61e9dd53-b5bb6c863b7ffbe83ad4b28d/cancel"

  req, _ := http.NewRequest("POST", url, payload)

  req.Header.Add("Accept", "application/json")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))

}

<?php
// Dependencies to install:
// $ composer require guzzlehttp/guzzle

require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.courier.com/messages/1-61e9dd53-b5bb6c863b7ffbe83ad4b28d/cancel', [
  'headers' => [
    'Accept' => 'application/json',
  ],
]);

echo $response->getBody();

Responses Example

{
  "event": "TAFGNB3GNQ4MZVHW4WV4R8Q8ZVN4",
  "id": "1-5e2b2615-05efbb3acab9172f88dd3f6f",
  "status": "DELIVERED",
  "recipient": "1-5e2b2615-05efbb3acab9172f88dd3f6f",
  "clicked": 1562611084123,
  "delivered": 1562611077139,
  "enqueued": 1562611073426,
  "error": "400 Bad Request",
  "notification": "TAFGNB3GNQ4MZVHW4WV4R8Q8ZVN4",
  "opened": 1562611083411,
  "runId": "1-5e2b2615-05efbb3acab9172f88dd3f6f",
  "sent": 1562611074138
}

{
  "event": "TAFGNB3GNQ4MZVHW4WV4R8Q8ZVN4",
  "id": "1-5e2b2615-05efbb3acab9172f88dd3f6f",
  "status": "DELIVERED",
  "recipient": "1-5e2b2615-05efbb3acab9172f88dd3f6f",
  "clicked": 1562611084123,
  "delivered": 1562611077139,
  "enqueued": 1562611073426,
  "error": "400 Bad Request",
  "notification": "TAFGNB3GNQ4MZVHW4WV4R8Q8ZVN4",
  "opened": 1562611083411,
  "runId": "1-5e2b2615-05efbb3acab9172f88dd3f6f",
  "sent": 1562611074138
}

A Note On Successful Cancellations

A successful cancellation will return a 200 status code along with the updated message record in the response body. Because the cancellation was a success, this message record will include a status of CANCELED as well as a canceledAt timestamp.

This successful response with status code 200 communicates a soft guarantee of message cancellation. It is still possible that the message has actually already been sent and that the SENT event is still on its way and has not been processed yet by the Courier Event Log Service.

A Note On `:message_id`

A successful call to POST /send returns a 202 status code along with a requestId in the response body.

For send requests that have a single recipient, the requestId is assigned to the derived message as its message_id. Therefore the requestId can be supplied to the Message’s API for single recipient messages.

For send requests that have multiple recipients (accounts, audiences, lists, etc.), Courier assigns a unique id to each derived message as its message_id. Therefore the requestId cannot be supplied to the Message’s API for single-recipient messages.

Example

Method: POST

URL: https://api.courier.com/messages/1-5e2b2615-05efbb3acab9172f88dd3f6f/cancel

Path Parameters​

Responses​

Request Example​

Responses Example​

A Note On Successful Cancellations​

A Note On :message_id​

Example​