[Skip to content](#main)

[→](/)

[![Avunu](/brand/avunu-logo.svg)![Avunu](/brand/avunu-logo-light.svg)](/)[Services](/services/)[Consulting](/services/consulting/)[ERP](/services/erp/)[Odoo](/services/erp/odoo/)[ERPNext](/services/erp/erpnext/)[Custom software](/services/custom-software/)[Devices & IoT](/services/devices-iot/)[Websites](/services/websites/)[Infrastructure](/services/infrastructure/)[Partners](/partners/)

[Work](/work/)[Open source](/open-source/)[Knowledge base](/kb/)[About](/about/)

[About Avunu](/about/)[Team](/about/team/)[Insights](/insights/)[Contact](/contact/)

[Client portal](https://erp.avunu.net/projects)[Start a project](/start/)

- [Services](/services/)[Consulting](/services/consulting/)
- [ERP](/services/erp/)
- [Odoo](/services/erp/odoo/)
- [ERPNext](/services/erp/erpnext/)
- [Custom software](/services/custom-software/)
- [Devices & IoT](/services/devices-iot/)
- [Websites](/services/websites/)
- [Infrastructure](/services/infrastructure/)
- [Partners](/partners/)

[Work](/work/)[Open source](/open-source/)[Knowledge base](/kb/)[About](/about/)

- [About Avunu](/about/)
- [Team](/about/team/)
- [Insights](/insights/)
- [Contact](/contact/)

[Client portal](https://erp.avunu.net/projects)[Start a project](/start/)

[Knowledge base](/kb/)[Linux](/kb/linux/)Release Stuck Messages in the Postal Mail Server Queue

Search the knowledge basePress/

ESC

Jump to

[Browse the knowledge base](/kb/)[Frappe](/kb/frappe/)[ERPNext](/kb/erpnext/)[Odoo](/kb/odoo/)[WordPress](/kb/wordpress/)[NixOS](/kb/nixos/)[Email](/kb/email/)[Linux](/kb/linux/)[Databases](/kb/databases/)[Containers](/kb/containers/)[Proxmox](/kb/proxmox/)[Git & Dev Tools](/kb/git-and-dev-tools/)

↵select↑↓navigateescclose

Search the knowledge base

[Skip to the article](#kb-article)[Linux](/kb/linux/)9 articles

- [Overview](/kb/linux/)
- [Clean Up Stale nginx Unix Sockets with a systemd Drop-in](/kb/linux/nginx-socket-cleanup-drop-in/)
- [Intel GPU Kernel Parameters](/kb/linux/intel-gpu-kernel-parameters/)
- [Media Conversion Recipes](/kb/linux/media-conversion-recipes/)
- [Mount a Drive with a systemd Mount Unit](/kb/linux/systemd-mount-units/)
- [Release Stuck Messages in the Postal Mail Server Queue](/kb/linux/postal-release-queued-messages/)
- [Set Up a WireGuard VPN Host](/kb/linux/wireguard-host-setup/)
- [Shell One-Liners](/kb/linux/shell-one-liners/)
- [Swap Configuration](/kb/linux/swap-configuration/)
- [Switch Commands with update-alternatives and sudo-rs](/kb/linux/sudo-rs-and-update-alternatives/)

Other sections[Frappe](/kb/frappe/)[ERPNext](/kb/erpnext/)[Odoo](/kb/odoo/)[WordPress](/kb/wordpress/)[NixOS](/kb/nixos/)[Email](/kb/email/)[Databases](/kb/databases/)[Containers](/kb/containers/)[Proxmox](/kb/proxmox/)[Git & Dev Tools](/kb/git-and-dev-tools/)

In Linux: 9 articles

[Overview](/kb/linux/)[Clean Up Stale nginx Unix Sockets with a systemd Drop-in](/kb/linux/nginx-socket-cleanup-drop-in/)[Intel GPU Kernel Parameters](/kb/linux/intel-gpu-kernel-parameters/)[Media Conversion Recipes](/kb/linux/media-conversion-recipes/)[Mount a Drive with a systemd Mount Unit](/kb/linux/systemd-mount-units/)[Release Stuck Messages in the Postal Mail Server Queue](/kb/linux/postal-release-queued-messages/)[Set Up a WireGuard VPN Host](/kb/linux/wireguard-host-setup/)[Shell One-Liners](/kb/linux/shell-one-liners/)[Swap Configuration](/kb/linux/swap-configuration/)[Switch Commands with update-alternatives and sudo-rs](/kb/linux/sudo-rs-and-update-alternatives/)

Other sections[Frappe](/kb/frappe/)[ERPNext](/kb/erpnext/)[Odoo](/kb/odoo/)[WordPress](/kb/wordpress/)[NixOS](/kb/nixos/)[Email](/kb/email/)[Databases](/kb/databases/)[Containers](/kb/containers/)[Proxmox](/kb/proxmox/)[Git & Dev Tools](/kb/git-and-dev-tools/)

LinuxRelease Stuck Messages in the Postal Mail Server Queue

Clear stale locks and retry delays on Postal's queued_messages table so stuck outbound mail is picked up and delivered again.

UpdatedOct 1, 2026

Applies toPostal v3

Tagspostalemailmariadbtroubleshooting

Reading time2 min

On this page[1. Check the Queue](#1-check-the-queue)[2. Stop the Workers](#2-stop-the-workers)[3. Release the Locks](#3-release-the-locks)[4. Start Postal Again](#4-start-postal-again)[From the Rails Console](#from-the-rails-console)

[Postal](https://docs.postalserver.io/) workers lock each outbound message while they process it. If a worker crashes or the server restarts mid-delivery, messages can stay locked or keep waiting on a long retry delay, so the queue stops draining. Releasing the locks puts those messages back in front of the workers.

Warning

Postal treats a lock older than `queued_message_lock_stale_days` (one day by default) as stale and **removes the message without retrying it**. Release stuck messages promptly, within that window, or they'll be dropped.

## 1. Check the Queue

Connect to Postal's main MariaDB database (named `postal` by default; see `main_db` in `postal.yml`) and look at what's waiting:

```
<span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">SELECT</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">COUNT</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">(</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">*</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">) </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">AS</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> queued,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">       </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">SUM</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">(locked_by </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">IS NOT NULL</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">) </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">AS</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> locked,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">       </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">SUM</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">(retry_after </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">></span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">NOW</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">()) </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">AS</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> waiting_to_retry</span>
<span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">FROM</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> queued_messages;</span>
```

To see the oldest locks:

```
<span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">SELECT</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> id, domain, locked_by, locked_at, retry_after, attempts</span>
<span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">FROM</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> queued_messages</span>
<span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">WHERE</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> locked_by </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">IS NOT NULL</span>
<span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">ORDER BY</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> locked_at</span>
<span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">LIMIT</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">20</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">;</span>
```

## 2. Stop the Workers

Stop Postal's worker processes so no message is being processed when you clear its lock. Otherwise a message could be delivered twice. With the standard Docker-based install:

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">postal</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">stop</span>
```

## 3. Release the Locks

Clear the lock and retry fields on every queued message:

```
<span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">UPDATE</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> queued_messages</span>
<span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">SET</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> locked_by </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">NULL</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    locked_at </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">NULL</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    retry_after </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">NULL</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">;</span>
```

To release only some messages, add a `WHERE` clause, for example `WHERE domain = 'example.com'` or `WHERE locked_at < NOW() - INTERVAL 1 HOUR`.

## 4. Start Postal Again

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">postal</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">start</span>
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">postal</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">logs</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">worker</span>
```

Watch the worker logs to confirm the messages are being sent. If they lock up again straight away, the underlying cause (DNS, the remote server refusing connections, or an IP blocklisting) is still there, and the message's delivery log in the Postal web interface usually shows it.

## From the Rails Console

The same release can be done through Postal's application console instead of raw SQL:

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">postal</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">console</span>
```

```
<span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">QueuedMessage</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">.</span><span style="--shiki-dark:#D2A8FF;--shiki-light:#8250DF">update_all</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">(</span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">locked_by:</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">nil</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">, </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">locked_at:</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">nil</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">, </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">retry_after:</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">nil</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">)</span>
```

Sources

- [docs.postalserver.io](https://docs.postalserver.io/)
- [github.com/postalserver/postal/blob/main/db/schema.rb](https://github.com/postalserver/postal/blob/main/db/schema.rb)
- [github.com/postalserver/postal/blob/main/app/models/queued_message.rb](https://github.com/postalserver/postal/blob/main/app/models/queued_message.rb)

Need help with Linux servers?

Our notes can take you a long way, but sometimes you'd rather have someone who's done it before.

[Managed infrastructure](/services/infrastructure/)

[← PreviousMount a Drive with a systemd Mount Unit](/kb/linux/systemd-mount-units/)[Next →Set Up a WireGuard VPN Host](/kb/linux/wireguard-host-setup/)

CC0This article is in the public domain ([CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/)), code samples included. Use it however helps you.

On this page

- [1. Check the Queue](#1-check-the-queue)
- [2. Stop the Workers](#2-stop-the-workers)
- [3. Release the Locks](#3-release-the-locks)
- [4. Start Postal Again](#4-start-postal-again)
- [From the Rails Console](#from-the-rails-console)

[Back to top↑](#top)

Services

- [ERP implementation](/services/erp/)
- [Odoo](/services/erp/odoo/)
- [ERPNext](/services/erp/erpnext/)
- [Custom software](/services/custom-software/)
- [Devices & IoT](/services/devices-iot/)
- [Websites](/services/websites/)
- [Infrastructure](/services/infrastructure/)

Resources

- [Our work](/work/)
- [Open source](/open-source/)
- [Knowledge base](/kb/)
- [Insights](/insights/)

Company

- [About](/about/)
- [Team](/about/team/)
- [Partners](/partners/)
- [Contact](/contact/)

Clients

- [Project portal](https://erp.avunu.net/projects)
- [Invoices](https://erp.avunu.net/)
- [Support](https://erp.avunu.net/)

[![Avunu](/brand/avunu-logo-light.svg)](/)[\<av-icon data-jx-static>\<svg viewBox="0 0 24 24" width="20" height="20" fill="currentColor" stroke="none" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false">\<path d="M20.400 20.500h-3.600v-5.600c0-1.300 0-3-1.800-3s-2.100 1.400-2.100 2.900v5.700H9.400V9h3.400v1.600c.5-.9 1.600-1.900 3.400-1.900 3.600 0 4.300 2.400 4.300 5.500v6.300zM5.300 7.400a2.100 2.100 0 1 1 0-4.100 2.100 2.100 0 0 1 0 4.100zm1.800 13.100H3.600V9h3.500v11.500zM22.200 0H1.800C.8 0 0 .8 0 1.700v20.600c0 .9.800 1.700 1.800 1.700h20.400c1 0 1.800-.8 1.800-1.700V1.700C24 .8 23.200 0 22.200 0z">\</path>\</svg>\</av-icon>](https://www.linkedin.com/company/avunu)[\<av-icon data-jx-static>\<svg viewBox="0 0 24 24" width="20" height="20" fill="currentColor" stroke="none" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false">\<path d="M12 .3a12 12 0 0 0-3.8 23.4c.6.1.8-.3.8-.6v-2c-3.3.7-4-1.6-4-1.6-.6-1.4-1.4-1.8-1.4-1.8-1-.7.1-.7.1-.7 1.2.1 1.8 1.2 1.8 1.2 1 1.8 2.8 1.3 3.5 1 .1-.8.4-1.3.7-1.6-2.7-.3-5.5-1.3-5.5-5.9 0-1.3.5-2.4 1.2-3.2-.1-.3-.5-1.5.1-3.2 0 0 1-.3 3.3 1.2a11.500 11.500 0 0 1 6 0c2.300-1.500 3.300-1.200 3.300-1.200.6 1.700.2 2.900.1 3.200.8.8 1.200 1.900 1.200 3.200 0 4.600-2.800 5.600-5.500 5.900.4.400.8 1.100.8 2.200v3.300c0 .3.2.7.8.6A12 12 0 0 0 12 .3">\</path>\</svg>\</av-icon>](https://github.com/Avunu)[Client portal](https://erp.avunu.net/projects)[Start a project](/start/)

Avunu LLC · 948 East Philadelphia Street, York, PA 17403 · (717) 814-8540Knowledge base articles are in the public domain[Privacy](/privacy/)[Terms](/terms/)
