POST /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.

From IBM MQ 9.3.3, you can connect to either a local queue manager or a remote queue manager. The name that you specify for qmgrName depends on how your mqweb server is configured:

• If your mqweb server is configured to connect only to local queue managers, then use the name of the queue manager.
• If your mqweb server is configured to connect remote queue managers, then use the unique name for the queue manager as specified in the remote queue manager connection information.

You can determine whether your mqweb server is configured to connect to local queue managers or remote queue managers by using the dspmqweb properties command and viewing the mqRestMessagingConnectionMode property.

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.

The following headers must be sent with the request:

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.

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 is specified as a 48 character hexadecimal encoded string, representing 24 bytes. Do not prefix the value with "ID:", the REST API adds that string automatically.

For example: ibm-mq-md-correlationId: 414d5120514d4144455620202020202067d8bf5923582e02

ibm-mq-md-correlationId

This header sets the correlation ID of the created message. The correlation ID can take one of the following forms:

• A 48 character hexadecimal encoded string, representing 24 bytes, prefixed with the string "ID:". For example: ibm-mq-md-correlationId: ID:414d5120514d4144455620202020202067d8bf5923582e02
• An application-specific value. The value is an application-specific string: ibm-mq-md-correlationId: My-Custom-CorrelId

  If you specify this form of correlation ID, the message destination is targeted as WMQ_CLIENT_JMS_COMPLIANT, and therefore incorporates an MQRFH2 header.

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 is 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-priority

For the REST API V3, this header sets the priority of the created message. The header is specified as one of the following values:

asDestination

The message uses the priority specified in the DEFPRTY attribute of the underlying IBM MQ queue object.

This value is the default value.

Integer value

Specify the actual priority as an integer in the range 0-9.

For example: ibm-mq-md-priority: asDestination

For the REST API V1 and REST API V2, the message priority for POST is always 4.

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

ibm-mq-usr

This header sets the request message user-defined properties.

The properties have the following syntax:

ibm-mq-usr: property_name; user_value; user_type

property_name

The name of the user property being specified. This must be a valid JMS property name.

user_value

The value of the property.

user_type

The type of the property:

• boolean (true/false, MQBOOL)
• byte (8-bit integer, MQINT8)
• short (16-bit integer, MQINT16)
• integer (32-bit integer, MQINT32)
• long (64-bit integer, MQINT64)
• float (32-bit real, MQFLOAT32)
• double (64-bit real, MQFLOAT64)
• string (quoted string)

You can set multiple properties on a message. You can either specify multiple comma-separated properties in a single ibm-mq-usr request header, or you can use two or more separate instances of the ibm-mq-usr request header.

For example, you can set multiple user defined properties in a single header: ibm-mq-usr: userPropertyA;5;byte,userPropertyB;-10;integer

Or you can set multiple user defined properties in separate instances of the header:ibm-mq-usr: userPropertyA;5;byte ibm-mq-usr: userPropertyB;-10;integer

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.

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.

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

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, prefixed by the string ID:.

For example:

ibm-mq-md-messageId: ID:414d5120514d4144455620202020202067d8ce5923582f07

ibm-mq-resolved-qmgr

Specifies the name of the queue manager that was used for the request. If a unique name was used in the resource URL, this header identifies the name of the queue manager that is associated with that unique name. If the unique name used in the resource URL refers to a queue manager group, this header identifies which queue manager within the group was used.

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

• 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!"