> ## Documentation Index
> Fetch the complete documentation index at: https://docs.waterr.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Limits and known gaps

> What the service enforces, and the two constraints that shape what is practical today.

## Known gaps

Two current limitations will change how you design against this. Both are being worked on; neither is hidden behind a support ticket.

### Cold outbound is unreliable

A message to someone who has **never corresponded with the inbox before** may not arrive, and you may not be told.

The sending domain currently publishes a soft-fail `SPF` record and **no `DKIM` signature**. Strict receivers — Gmail among them — treat unauthenticated mail from an unfamiliar sender as spam, and often discard it silently rather than bouncing it. The send will report success, and the mail simply will not appear.

Replies into an existing conversation are unaffected. An established thread carries the relationship signals that get mail delivered, and those land in the inbox normally.

| Pattern                                | Works today    |
| -------------------------------------- | -------------- |
| Agent replies to an inbound message    | Yes            |
| Agent follows up on an existing thread | Yes            |
| Agent emails a brand-new contact first | **Unreliable** |

<Warning>
  Design reply-driven agents now; treat outbound-first campaigns as not yet supported. If your use case depends on first contact, say so when you request access — there is a configuration path for it, it just is not the default.
</Warning>

### Attachment bodies are not stored

Attachment **metadata** is captured — filename, content type, size — and appears on the message. The **bytes** are not retained on the current deployment, so fetching an attachment returns nothing.

Everything else about a message carrying an attachment works normally: it is parsed, threaded, stored, and your agent can see that a file was attached and what it was called. It just cannot read the contents.

Outbound attachments are unaffected; you can send them.

## Size limits

| Limit                            | Value                                   |
| -------------------------------- | --------------------------------------- |
| Inbound message                  | 25 MiB — larger is rejected at the edge |
| Attachments per outbound message | 32                                      |
| Subject length                   | 998 characters                          |
| Username length                  | 64 characters                           |

## Rate limits

300 requests per 60 seconds, **per API key**. Over the limit returns `429 rate_limited` with `Retry-After: 60`.

Giving each agent its own scoped key isolates them, so one busy agent cannot throttle the rest.

## Webhook delivery

|                     |                      |
| ------------------- | -------------------- |
| Attempts            | 6                    |
| Backoff             | 1m, 5m, 30m, 2h, 12h |
| Timeout per attempt | 30 seconds           |
| Success             | Any `2xx`            |

Total window is roughly 15 hours before a delivery is marked `failed`.

## Event types that never fire

`message.delivered`, `message.bounced` and `message.complained` are accepted on subscriptions but do not fire on this deployment — they need asynchronous feedback from the mail transport that is not available today. They are accepted so client code stays portable across mailbox APIs.

Do not build logic that waits for them. In particular, absence of `message.bounced` is **not** evidence of delivery.

## Storage

Each inbox is backed by its own SQLite database with a 10 GB ceiling. In practice that is hundreds of thousands of messages, so it is unlikely to bind before something else does — but it is per inbox, not pooled, so a single very busy address is the case to watch.
