POST
You can use the HTTP POST method with the
/messaging/qmgr/{qmgrName}/queue/{queueName}/message
resource to put messages to the associated queue manager and queue.
Puts an IBM® MQ message containing the HTTP request body to the specified
queue manager and queue. 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/v1/messaging/qmgr/{qmgrName}/queue/{queueName}/message
- qmgrName
- Specifies the name of the queue manager to connect to for messaging.
- 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 sent with a value that is the content of the
csrfToken
cookie. The content of thecsrfToken
cookie is used to confirm that the credentials that are being used to authenticate the request are being used by the owner of the credentials. That is, the token is used to prevent cross-site request forgery attacks.
- 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
(default)- The message does not expire.
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
(default)- 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]
4
.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.
- 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. - The queue that is specified by the {queueName} portion of the resource
URL, must be
PUT
enabled.
On UNIX, Linux®, and Windows, you can grant authority to security principals to use IBM MQ resources by using the mqsetaut command. For more information, see mqsetaut.
On z/OS®, see Setting up security on z/OS.
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.
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
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/v1/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.
For IBM MQ 9.0.4 and earlier, after the user is logged in, the LTPA token and CSRF token are used to authenticate further requests.
token_value
is the value of the
csrfToken
cookie, and from IBM MQ 9.0.5
token_value
is 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/v1/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/v1/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/v1/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!"