Publishing Messages

In AMQP publish a message is an asynchronous operation, which avoids the latency of a synchronous operation but makes it harder to correctly handle errors. See Synchronous/Asynchronous Model for more details about asynchronous methods and workarounds.

The method to publish a method is this:

Channel.basic_publish(exchange='', routing_key='', mandatory=False, immediate=False, headers={}, body='')


This is an asynchronous method.

This method publishes a message to a specific exchange.

The message will be routed to queues as defined by the exchange configuration and distributed to any active consumers when the transaction, if any, is committed.

  • exchange – Specifies the name of the exchange to publish to. The exchange name can be empty, meaning the default exchange. If the exchange name is specified, and that exchange does not exist, the server will raise a channel exception.
  • routing_key – Specifies the routing key for the message. The routing key is used for routing messages depending on the exchange configuration.
  • mandatory – This flag tells the server how to react if the message cannot be routed to a queue. If this flag is set, the server will return an unroutable message with a Return method. If this flag is zero, the server silently drops the message.
  • immediate – This flag tells the server how to react if the message cannot be routed to a queue consumer immediately. If this flag is set, the server will return an undeliverable message with a Return method. If this flag is zero, the server will queue the message, but with no guarantee that it will ever be consumed.

Basic Message Properties

There are dozens of options regarding the reliability and durability of message delivery as well as immediate and mandatory, which can be passed as the headers parameter to Channel.basic_publish() above.

The following properties are defined in the AMQP specification:

(shortstr) content-type

The MIME content type of the message.

(shortstr) content-encoding

The MIME content encoding of the message.

(octet) delivery-mode

For queues that are persistent, specify whether the message should be persisted:

  • 1 if the message should be non-persistent.
  • 2 if the message should be persistent.
(octet) priority

The priority of the message, a value from 0 to 9. Higher-priority messages will be delivered before all lower-priority messages (if the queue supports it).

(shortstr) correlation-id

Application correlation identifier, for application use.

(shortstr) reply-to

Address to reply to. For application use. No formal behaviour but may hold the name of a private response queue, when used in request messages.

(shortstr) expiration

Message expiration specification. For implementation use, no formal behaviour.

(shortstr) message-id

Application message identifier. For application use, no formal behaviour.

(timestamp) timestamp

Message timestamp. For application use, no formal behaviour.

(shortstr) type

Message type name. For application use, no formal behaviour.

(shortstr) user-id

The user ID of the publishing application. AMQP specifies no formal behaviour for this property, but RabbitMQ validates that it matches the login username.

(shortstr) app-id

The application ID of the publishing application. For application use, no formal behaviour.

Any property not in the above list will be sent as part of the headers table:

(table) headers

Application-defined headers; also used for header exchange routing.

Note that RabbitMQ provides an extension for CC- and BCC-style lists of additional routing keys, which are also passed as headers:

(array of longstr) CC

Additional routing keys to deliver the message to.

(array of longstr) BCC

Additional routing keys to deliver the message to. This header will be removed from the headers table before the message is delivered.

Returned Messages

AMQP can return a message to the sender if either the immediate or mandatory attributes are set. It is possible to test whether a message has been returned:


Raise an error if a message has been returned.

This also clears the returned frame, with the intention that each basic.return message may cause at most one MessageReturned error.

The exception that is raised is

class nucleon.amqp.exceptions.MessageReturned[source]

A message was not delivered.

The first argument will be the message that was returned.

or one of the subclasses:

class nucleon.amqp.exceptions.MessageReturnedNoRoute[source]

A message was not delivered because there was no binding to do so.

class nucleon.amqp.exceptions.MessageReturnedNoConsumers[source]

A message was not delivered because nothing was accepting.

If the context manager is used, this check will automatically be made when the context manager is left (assuming there has been no more significant exception):

with as channel:
# Exception will be raised before we get to the next statement
return True

Publish Confirmation (RabbitMQ Extension)

RabbitMQ supports confirms or publish acknowledgements, which allow a publisher to know when a message has been processed. The alternative is to use transactions.

Publish acknowledgements can be enabled on a per-channel basis by calling Channel.confirm_select(), which is normally synchronous but can be called in an asynchronous mode if the optional nowait parameter is True.

After this call, Channel.basic_publish() will block until it receives an acknowledgement.


This method sets the channel to use publisher acknowledgements.

The client can only use this method on a non-transactional channel.

Parameters:nowait – If set, the server will not respond to the method. The client should not wait for a reply method. If the server could not complete the method it will raise a channel or connection exception.

After a channel that has been enabled for publish confirms, basic_publish() will raise a MessageReturned exception if the outgoing message is returned.

Table Of Contents

Previous topic

Queues and Exchanges

Next topic

Consuming messages

This Page