> ## Documentation Index
> Fetch the complete documentation index at: https://docs.textyess.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Frequency cap
> How TextYess protects your contacts from over-messaging — the per-organisation cap, quiet hours, the per-execution ceiling, and how the rules differ for marketing vs utility messages.
The frequency cap is a safety net. It limits how often any single contact receives a **marketing** message from your account — protecting your sender reputation with Meta and your customer's inbox at the same time.
It applies **per organisation**, **per contact**, **per channel**. It is enforced at runtime by every Send Message and Send Dynamic Message step, automatically.
## The two settings
You configure the cap once in **Settings → Frequency cap**. The same configuration applies to every flow you run.
The maximum number of MARKETING messages a single contact can receive in a rolling window (e.g. "no more than 3 marketing messages per 7 days").
A timezone-aware window when no message goes out, regardless of category (e.g. "no sends between 22:00 and 09:00 Europe/Rome"). Marketing and utility sends both honour it.
## How the cap behaves per category
The cap behaves differently depending on the template's **category**:
| Category | Rate-limit check | Quiet-hours check |
| ------------- | --------------------------- | ----------------- |
| **MARKETING** | ✅ Counted against the limit | ✅ Honoured |
| **UTILITY** | ❌ Not counted | ✅ Honoured |
A marketing message that would exceed the limit is **skipped**, not delayed. A utility message that would land in quiet hours **waits** for quiet hours to end and then sends.
Order confirmations and other utility sends never get blocked by the marketing cap — exactly what you want. But they still respect quiet hours so customers aren't woken up by a 3 a.m. shipping notification.
## How the cap fits into a flow
When a Send Message or Send Dynamic Message executes:
For Send Message, TextYess looks up the template's **actual** category as approved by Meta (not just what you submitted). For Send Dynamic Message, it uses the step's configured category.
* MARKETING → count recent marketing messages to this contact; if over the limit, **skip the send** and record the skip reason.
* UTILITY → skip the count check.
If the current time in the configured timezone falls inside the quiet-hours window, sleep until quiet hours end and re-check the cap. Then send.
On success, log a row to the message-log so the next cap check sees this message in its count.
## Skipped sends: what you'll see
When a marketing send is blocked by the cap, the step does **not** send and writes a skip record to memory:
```
memory[stepId].reply = {
type: "skipped",
reason: "frequency_cap"
}
```
The flow does not fail — it continues normally. If the next step is a Conditional Split that branches on the message being delivered, the False branch fires. If it's a fixed next-step, the flow runs that next step regardless.
Skipped sends are recorded on the execution, so you can inspect them after the fact.
When a downstream step depends on the message actually being delivered, branch on it with a [Conditional Split](/flows/conditions): `.reply.type != "skipped"`.
## The hard ceiling
In addition to the configurable cap, TextYess enforces a **hard ceiling of 10 sends per execution, per contact, regardless of category**. This is a backstop — most flows send 1-3 messages. The ceiling exists to prevent runaway loops if a misconfigured flow somehow keeps sending.
If the ceiling trips:
```
memory[stepId].reply = {
type: "skipped",
reason: "hard_ceiling"
}
```
This will only ever bite you if a flow's logic loops back to a send step many times in one execution. If you see this in your execution records, treat it as a configuration error.
## What counts as "marketing"
TextYess uses **Meta's** approval of the template, not just what you marked in the editor. This matters because:
* You can submit a template as UTILITY and Meta can downgrade it to MARKETING (which it routinely does for promotional language). After the downgrade, the cap automatically tightens for that template's sends — without you re-publishing the flow.
* The reverse is also true: Meta sometimes upgrades a borderline MARKETING template to UTILITY. Future sends bypass the count check immediately.
For **Send Dynamic Message**, there is no Meta-approved category per send (the dynamic template's category was approved once and applies to all sends through it), so the step's configured category is used directly.
## Best practices
A common starting point: 3 marketing messages per 7 days. Increase only if open rates and unsubscribes stay healthy.
Configure quiet hours in your customers' timezone, not your own. If you sell internationally, use your single largest market — the cap is global per organisation.
The UI already defaults to UTILITY. Promote to MARKETING only for genuinely promotional content. Mislabelling MARKETING as UTILITY is a Meta policy violation and will get the template rejected on review.
If your flow's logic assumes "the message was sent", branch on `.reply.type != "skipped"` so cap-blocked customers don't get dropped on the floor.
## FAQ
The cap is checked **per send**, not per execution. So a flow with two marketing messages will run both executions, but if the contact has already hit the cap, both messages will skip. The execution doesn't fail — it just records the skips.
Yes. The count query only looks at MARKETING messages. A contact can receive any number of UTILITY messages (order confirmations, shipping updates, OTPs) without the cap reacting — quiet hours still apply.
The new cap applies to all subsequent sends, including from in-flight executions. There's no transition window.
No. It only counts messages TextYess sent. If you have multiple sending tools on the same number, plan caps holistically.
Use the UTILITY category if the message is genuinely transactional — it bypasses the count check. There is no way to bypass quiet hours; that's a hard rule.
Next: [Publishing & testing](/flows/publishing-testing) — how to take a flow from draft to live without sending anything you didn't mean to.