POST
You 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
v1
where the URL uses v2
. For example, the first
part of the URL is as follows:
https://host:port/ibmmq/rest/v1/
- 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.
- queueName
- Specifies the name of the queue on which to put the message.
You can use HTTP instead of HTTPS if you enable HTTP connections. For more information about enabling HTTP, see Configuring HTTP and HTTPS ports.
Request headers
- Authorization
- This header must be sent if you are using basic authentication. For more information, see Using 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
- ibm-mq-rest-csrf-token
- This header must be set, but the value can be anything, including being blank.
- 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.
- 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.
- Integer value
- Milliseconds before message expiry.
- 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.
- 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]
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.
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 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, you 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 Setting up security on z/OS.
If you 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.
- 401
- Not authenticated.
- 403
- Not authorized.
- 404
- Queue does not exist.
- 405
- Queue is PUT inhibited.
- 415
- A message header or body is 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
- 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 isapplication/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.
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 IBM MQ 9.1.5 you must use the v1 resource URL instead. That is, in
the resource URL, substitute v1
where the example URL uses v2
.
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 managerQM1
, 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 managerQM1
, 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 managerQM1
, 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!"