POST

We can use the HTTP POST method with the /messaging/qmgr/{qmgrName}/queue/{queueName}/message resource to put messages to the specified queue on the specified queue manager.

Puts an IBM MQ message containing the HTTP request body to the specified queue manager and queue. The queue manager must be on the same machine as the mqweb server. The method only supports text based HTTP request bodies. Messages are sent as MQSTR formatted messages, and are put using the current user context.


Resource URL

https://host:port/ibmmq/rest/v2/messaging/qmgr/{qmgrName}/queue/{queueName}/message

    qmgrName
    Specifies the name of the queue manager to connect to for messaging. The queue manager must be on the same machine as the mqweb server.
    The queue manager name is case-sensitive.
    If the queue manager name includes a forward slash, a period, or a percent sign, these characters must be URL encoded:

    • A forward slash must be encoded as %2F.
    • A period must be encoded as %2E.
    • A percent sign must be encoded as %25.

    queueName
    Specifies the name of the queue on which to put the message.
    The queue must be defined as being local, remote, or an alias to the specified queue manager - it may also reference a clustered queue.
    The queue name is case sensitive.
    If the queue name includes a forward slash or a percent sign, these characters must be URL encoded:

    • A forward slash, /, must be encoded as %2F.
    • A percent sign, %, must be encoded as %25.

We can use HTTP instead of HTTPS if you enable HTTP connections. For more information about enabling HTTP, see Configure HTTP and HTTPS ports.


Request headers

The following headers must be sent with the request:

    Authorization
    This header must be sent if we are using basic authentication. For more information, see Use HTTP basic authentication with the REST API.

    Content-Type
    This header must be sent with one of the following values:

    • text/plain;charset=utf-8
    • text/html;charset=utf-8
    • text/xml;charset=utf-8
    • application/json;charset=utf-8
    • application/xml;charset=utf-8

    Note: If charset is omitted from the Context-Type header, UTF-8 is assumed.

    ibm-mq-rest-csrf-token
    This header must be set, but the value can be anything, including being blank.

The following headers can optionally be sent with the request:

    Accept-Language
    This header specifies the required language for any exceptions or error messages returned in the response message body.

    ibm-mq-md-correlationId
    This header sets the correlation ID of the created message. The header must be specified as a 48 character hexadecimal encoded string, representing 24 bytes.
    For example:
    ibm-mq-md-correlationId: 414d5120514d4144455620202020202067d8bf5923582e02

    ibm-mq-md-expiry
    This header sets the expiry duration for the created message. The expiry of a message starts from the time the message arrives on the queue. As a result network latency is ignored. The header must be specified as one of the following values:

      unlimited
      The message does not expire.
      This value is the default value.

      Integer value
      Milliseconds before message expiry.
      Limited to the range 0 - 99999999900.

    ibm-mq-md-persistence
    This header sets the persistence for the created message. The header must be specified as one of the following values:

      nonPersistent
      The message does not survive system failures or queue manager restarts.
      This value is the default value.

      persistent
      The message survives system failures or queue manager restarts.

    ibm-mq-md-replyTo
    This header sets the reply-to destination for the created message. The format of the header uses the standard notation of supplying the reply-to queue and an optional queue manager: replyQueue[@replyQmgr]
    For example: 
    ibm-mq-md-replyTo: myReplyQueue@myReplyQMgr


Request body format

The request body must be text and use UTF-8 encoding. No specific text structure is required. An MQSTR formatted message containing the request body text is created and put to the specified queue.

For more information, see examples.

Note:

Newlines in incoming strings are removed by the HTTP POST operation. REST applications should not use newlines in messages that are sent or published using the REST API, as they will be lost.


Security requirements

The caller must be authenticated to the mqweb server. The MQWebAdmin and MQWebAdminRO roles are not applicable for the messaging REST API. For more information about security for the REST API, see IBM MQ Console and REST API security.

Once authenticated to the mqweb server the user is capable of using both the messaging REST API and the administrative REST API.

The security principal of the caller must be granted the ability to put messages to the specified queue:

  • The queue that is specified by the {queueName} portion of the resource URL, must be PUT enabled.
  • For the queue that is specified by the {queueName} portion of the resource URL, +PUT authority must be granted to the security principal of the caller.
  • For the queue that is specified by the {queueName} portion of the resource URL, UPDATE access must be granted to the security principal of the caller.

On UNIX, Linux, and Windows, we can grant authority to security principals to use IBM MQ resources by using the setmqaut command. For more information, see setmqaut (grant or revoke authority).

On z/OS, see Set up security on z/OS.

If we use Advanced Message Security (AMS) with the messaging REST API, note that all messages are encrypted by using the context of the mqweb server, not the context of the user that posts the message.


Response status codes

    201
    Message created and sent successfully.

    400
    Invalid data provided.
    For example, an invalid request header value was specified.

    401
    Not authenticated.
    The caller must be authenticated to the mqweb server and must be a member of one or more of the MQWebAdmin, MQWebAdminRO, or MQWebUser roles. The ibm-mq-rest-csrf-token header must also be specified. For more information, see Security requirements.

    403
    Not authorized.
    The caller is authenticated to the mqweb server and is associated with a valid principal. However, the principal does not have access to all, or a subset of the required IBM MQ resources, or is not in the MQWebUser role. For more information about the access that is required, see Security requirements.

    404
    Queue does not exist.

    405
    Queue is PUT inhibited.

    415
    A message header or body is an unsupported media type.
    For example, the Content-Type header is set to an unsupported media type.

    500
    Server issue or error code from IBM MQ.

    502
    The current security principal cannot send the message as the messaging provider does not support the required function. For example, if the mqweb server class path is invalid.

    503
    Queue manager not running.


Response headers

The following headers are returned with the response:

    Content-Language
    Specifies the language identifier of the response message in the event of any errors or exceptions. Used in conjunction with Accept-Language request header to indicate the required language for any error or exception conditions. The mqweb server default is used if the requested language is unsupported.

    Content-Length
    Specifies the length of the HTTP response body, even when there is no content. Upon success the value is zero.

    Content-Type
    Specifies the type of response body. Upon success the value is text/plain;charset=utf-8. In the event of any errors or exceptions, the value is application/json;charset=utf-8.

    ibm-mq-md-messageId
    Specifies the message ID that is allocated by IBM MQ to this message. Like the ibm-mq-md-correlationId request header, it is represented as a 48 character hexadecimal encoded string, representing 24 bytes.
    For example:
    ibm-mq-md-messageId: 414d5120514d4144455620202020202067d8ce5923582f07

Note: The default message priority for POST is 4.


Response body format

The response body is empty if the message is sent successfully. If an error occurs, the response body contains an error message. For more information, see REST API error handling.


Examples

The following examples use the v2 resource URL. If you are using a version of IBM MQ earlier than Version 9.1.5 we must use the v1 resource URL instead. That is, in the resource URL, substitute v1 where the example URL uses v2.

The following example logs in a user called mquser with the password mquser. In cURL, the log in request might look like the following Windows example. The LTPA token is stored in the cookiejar.txt file by using the -c flag: 
curl -k "https://localhost:9443/ibmmq/rest/v2/login" -X POST 
-H "Content-Type: application/json" --data "{\"username\":\"mquser\",\"password\":\"mquser\"}" 
-c c:\cookiejar.txt

After the user is logged in, the LTPA token and ibm-mq-rest-csrf-token HTTP header are used to authenticate further requests. The ibm-mq-rest-csrf-token token_value can be any value, including blank.

  • The following Windows cURL example sends a message to queue Q1 on queue manager QM1, using default options. The message contains the text "Hello World!": 
    curl -k "https://localhost:9443/ibmmq/rest/v2/messaging/qmgr/QM1/queue/Q1/message" 
-X POST -b c:\cookiejar.txt -H "ibm-mq-rest-csrf-token: token_value" 
-H "Content-Type: text/plain;charset=utf-8" --data "Hello World!"
  • The following Windows cURL example sends a persistent message to queue Q1 on queue manager QM1, with an expiry of 2 minutes. The message contains the text "Hello World!": 
    curl -k "https://localhost:9443/ibmmq/rest/v2/messaging/qmgr/QM1/queue/Q1/message" 
-X POST -b c:\cookiejar.txt -H "ibm-mq-rest-csrf-token: token_value" 
-H "Content-Type: text/plain;charset=utf-8" -H "ibm-mq-md-persistence: persistent" 
-H "ibm-mq-md-expiry: 120000" --data "Hello World!"
  • The following Windows cURL example sends a non-persistent message to queue Q1 on queue manager QM1, with no expiry and defined correlation ID. The message contains the text "Hello World!": 
    curl -k "https://localhost:9443/ibmmq/rest/v2/messaging/qmgr/QM1/queue/Q1/message" 
-X POST -b c:\cookiejar.txt -H "ibm-mq-rest-csrf-token: token-value" 
-H "Content-Type: text/plain;charset=utf-8" -H "ibm-mq-md-persistence: nonPersistent" 
-H "ibm-mq-md-expiry: unlimited" -H "ibm-mq-md-correlationId: 414d5120514d4144455620202020202067d8b
f5923582e02" --data "Hello World!"

Parent topic: /messaging/qmgr/{qmgrName}/queue/{queueName}/message