Sending · November 6, 2026
Pause a mail burst and notify the owner
A password-reset route can pass a filter id. Twenty messages in ten minutes on that id, or to the same mailbox, pause that key for an hour. The account owner gets one incident note.
Bots hit a reset form and spend the plan on mail nobody asked for. Pass filter.transaction_id on the send: a stable id for the person or the request. Pigeon counts that id and the recipient mailbox, and stops the burst before those messages are stored.
What the caller sends
- filter.transaction_id is 1 to 128 characters. Letters, numbers, and . _ : @ + - are allowed. The first character is a letter or a number.
- SMTP uses the headers X-Pigeon-Filter-Transaction-Id and X-Pigeon-Filter-Admin. They match the same fields on the HTTP API.
- A blank or missing transaction id skips the filter. Mail without a filter keeps sending.
- An invalid id is refused. The API returns 422. SMTP returns 550.
Twenty in ten minutes
Each transaction id can send 20 messages in 10 minutes. Each mailbox can receive 20 in the same window. The 21st is refused for 60 minutes. That message is not stored, so it stays out of the plan. The API answers 429 with the name filter_stopped. SMTP answers 451.
Mail to one admin
- Set filter.admin to true when many legitimate messages should reach one mailbox, such as an admin inbox. The strings true, 1, yes, and on count as true.
- That skips the mailbox bucket only. A repeated transaction id still pauses at 20.
- Unique transaction ids with filter.admin true can keep sending to that mailbox.
The pause covers that filter key
The pause covers that filter key: the transaction id, the mailbox, or both. Other mail from the same API key keeps sending. A different transaction id to a different address still goes out. A new transaction id to a mailbox that already paused stays paused. Another account can use the same transaction id on its own sends.
The pause lasts 60 minutes and outlives the 10 minute counting window. After it ends, and the window has expired, the key can send again. A later incident can notify the owner again.
One notice to the owner
The first time a key pauses, each account owner receives one email. The subject is A mail burst was paused. The note says an incident was detected and that sending for that key is temporarily stopped. It names the transaction id, the mailbox, or both, and it says the pause lasts 60 minutes. Further refusals during that pause do not send another note.
Newsletters, broadcasts, and marketing campaigns do not pass this filter. This pause is separate from the account pause that follows a bounce rate above 4%.
Send an email Block a complaint and pause a high bounce rate