Abuse controls
This page lists the limits of each trust tier and the events that pause mail or suspend an organization. Operators use it to review abuse reports and to change a tier, suspend an organization or end a mail pause.
Quick start
For customers:
- Open the console’s Usage page to see your tier and its limits. The API returns the same data at
GET /v1/orgs/{id}/usage. - Over each rolling 24 hours, keep bounces under 5% and complaints under 0.1% of your mail. Above that, Pushleft pauses your mail until an operator ends the pause (details).
- If your organization is suspended, read the reason on the Usage page or in the API error. You can still sign in, read and export your data.
To report abuse on a site that Pushleft hosts, send a report. You do not need an account:
curl -X POST https://api.pushleft.dev/v1/abuse/reports \
-H 'Content-Type: application/json' \
-d '{"reporter_email": "[email protected]", "target": "https://shop.example.com/login", "category": "phishing", "body": "What you saw and when."}'
For operators, run these commands on the control plane with the migration-owner DATABASE_URL:
-
List the open reports, then read one:
pushleft-api abuse list pushleft-api abuse show <report-id> -
Resolve the report, or suspend the organization and resolve the report in one step:
pushleft-api abuse resolve <report-id> --resolution "not hosted on Pushleft" pushleft-api abuse suspend <report-id> --reason "confirmed phishing" -
Raise the tier of an organization that you trust:
pushleft-api org show <org-id> pushleft-api org set-tier <org-id> standard --reason "verified business, 30 days clean"
Scope and operator commands
Pushleft runs customer code and will send customer mail from its own IP addresses. One abusive organization can get the platform’s IP addresses blocked for everyone. This page describes the core controls:
- Trust tiers, the approval for Pushleft servers and the role resource override.
- The suspend switch.
- Abuse report intake.
- Mail quotas with an automatic pause.
- The audit trail.
There is no content scanning and no CPU-mining detection.
Operator commands run as pushleft-api <command> with the migration-owner or a BYPASSRLS DATABASE_URL. Each command prints JSON. The operator name in the audit trail is --operator <name>, or $USER if you do not give one.
Trust tiers
A trust tier sets how much an organization can use before an operator trusts it more. Every organization has a tier: new, standard or trusted. New organizations start as new. Organizations that existed before migration 0052 became standard.
Limit (org_tiers) | new | standard | trusted | Enforced by |
|---|---|---|---|---|
max_active_deployments (queued, building or deploying) | 5 | 20 | platform cap | API, 429 deployment_quota |
mail_per_day (rolling 24 h) | 100 | 10 000 | 100 000 | mail_send_allowed() |
egress_gb_per_day | 10 | 200 | 2 000 | stored and shown only; the node agent does not enforce it yet (gap) |
ai_requests_per_day | 500 | 20 000 | 200 000 | AI proxy, 429 daily_quota per UTC day (ai-proxy.md) |
git_max_repositories | 3 | 50 | none | API, 429 git_repository_quota (git.md) |
git_max_repository_mb | 200 | 1 024 | 5 120 | the git pre-receive hook refuses the push |
error_events_per_day | 5 000 | 100 000 | 1 000 000 | error ingest, per UTC day: excess events dropped, SDKs told to back off (errors.md) |
error_retention_days | 14 | 30 | 90 | ClickHouse TTL of stored error events and spans (errors.md) |
- The deployment limit can only lower the platform-wide
PUSHLEFT_DEPLOYMENT_MAX_ACTIVE(handbook). ANULLlimit means that only the platform setting applies. - To change the limits, update
org_tiersas the owner. - Organizations see their tier and limits in
GET /v1/orgs/{id}/usageand on the console Usage page (usage API). - The tier also caps the retention settings.
To show an organization and change its tier:
pushleft-api org show <org-id>
pushleft-api org set-tier <org-id> standard --reason "verified business, 30 days clean"
Raising a tier. An operator can raise a tier by hand. The platform could also raise it automatically by age plus a payment method. No payment provider exists (billing), so the automatic path is not available. Raise tiers by hand, for example after a set age and a review of the organization’s activity.
Pushleft servers for a sign-up organization
An organization from sign-up uses its own servers at once. Pushleft’s servers need one approval, because customer code then runs on shared hardware and shared IP addresses.
-
The owner selects Pushleft servers in the console’s setup steps. The request state is
requested, and the operator gets a mail (PUSHLEFT_SIGNUP_MAIL_TO). -
The operator lists the open requests and approves one:
pushleft-api org cloud-requests pushleft-api org approve-cloud <org-id> --reason "verified business" -
Owners and admins get a mail. The organization can deploy on Pushleft servers from then on.
Until the approval, each placement keeps the organization’s work on nodes that it owns (org_own_nodes_only). The approval writes a cloud_access_approved audit event with the operator and the reason. An organization on a byo plan moves to the newest cloud plan. An approved organization keeps its approval when it changes back to its own servers. To take the access away, suspend the organization.
Role resource override
The tier caps the resources: of every role (org_tiers.max_role_cpu_millis and max_role_memory_mb):
new: 1000m / 1 GiB.standard: 2000m / 4 GiB.trusted: 4000m / 8 GiB.
On a paid plan (Cloud, or Cloud with your own servers), these caps do not apply: a role may ask for the manifest’s maximum (4 CPUs, 32 GiB), and its hours are billed (decided 2026-11-11, migration 0213). The caps apply on the self-hosted plan and to an organization with no plan.
To let one organization run larger roles without changing its tier, set an override:
pushleft-api org role-resources <org-id> --cpu-millis 4000 --memory-mb 16384 --reason "16 GiB workers, agreed with the customer"
pushleft-api org role-resources <org-id> clear --reason "no longer needed"
- A flag you leave out keeps the tier’s cap for that dimension.
- The override replaces the tier’s cap. It has no upper bound of its own beyond the manifest limit (4 CPUs, 32 GiB).
- The override does not make a role fit. The scheduler still refuses a role larger than every application node of the organization’s pool.
pushleft-api org showprints the current override asrole_resource_override.
Each override is a period in org_role_resource_overrides (migration 0098): effective_from, and effective_until once it is changed or cleared. Billing can join usage hours against those periods to charge for the override later. There is no price for it yet (billing). Every set, change and clear writes org_role_resources_changed with from, to, operator and reason.
Inviting a member
An operator can invite a person to an organization without a console session (built 2026-11-07, Waseem: add one owner to every organization):
pushleft-api org invite <org-id> [email protected] owner --reason "second owner account"
- Run it with the API’s environment (
PUSHLEFT_SMTP_URL,PUSHLEFT_MAIL_FROM,PUSHLEFT_CONSOLE_URL). The invitation is the same as one from Settings › Members: one token, valid for 7 days, mailed only to the invited address. Accepting it creates the account if there is none. - Without mail, the command prints the token and the link. Hand them to the person yourself.
- A new invitation to the same address replaces the pending one. An address that is already a member is refused: change its role in the console.
- The
invitation_createdaudit row has no user, and itsoperatorfield holds the operator and the reason.
Suspending an organization
Suspension stops an organization’s workloads and new work, and keeps all its data. To suspend and unsuspend:
pushleft-api org suspend <org-id> --reason "phishing kit on shop.example.com"
pushleft-api org unsuspend <org-id> --reason "appeal accepted"
The organization sees the reason in API errors and on the console Usage page, so write it for the customer. While an organization is suspended:
- API. The API refuses every change outside
/v1/auth/with403 org_suspended. The check runs in the request extractor, andcreate_deploymentchecks again inside its transaction. Reads and exports (everyGET) still work. Sign-in, sign-out, tokens and security settings still work, so the customer can see what happened and export data. - Scheduler. Queued work of the organization is not placed. The work waits and resumes after the organization is unsuspended.
- Workloads are scaled to zero. Releases are not published. The routes of every release are drained and removed (
remove_ingress). Thenstop_applicationstops and removes the containers, the same path that stops a superseded release. Volumes, databases and all rows are kept. - Mail and AI.
mail_send_allowed()returnsorg_suspended, and the AI proxy refuses every request with403 org_suspended.
After you unsuspend an organization, stopped releases do not restart by themselves. The customer deploys again (a new release supersedes the stopped one).
Known gaps:
- Managed database containers keep running, because the agent has no job that stops a database without removing it.
- Agent jobs that were already targeted at a node before the suspension can still be leased. The gateway does not check suspension.
- An application that one of these jobs starts after the stop job was queued keeps running until the next release.
Abuse reports
Anyone can report abuse on a site that Pushleft hosts. POST /v1/abuse/reports is public, with no sign-in and no captcha.
- It is rate limited to 5 reports per client address per hour and 200 per hour in total (
429 rate_limitedwithRetry-After). - The body must be at most 64 KiB.
{"reporter_email": "[email protected]", "target": "https://shop.example.com/login",
"category": "phishing", "body": "What you saw, when, and how to reproduce it."}
The categories are spam, phishing, malware, copyright, illegal_content, abuse_of_service and other.
To find the organization that serves the target, Pushleft matches its hostname first against platform hostnames (ingress_hostnames). Then it checks verified custom domains.
Reports are stored in abuse_reports, which has no tenant policy, so the reported organization never sees the reporter. When platform mail is configured and PUSHLEFT_ABUSE_NOTIFY_EMAIL is set, each report is also emailed to that address.
The operator queue:
pushleft-api abuse list [--all] # open reports, oldest first (without the body)
pushleft-api abuse show <report-id>
pushleft-api abuse resolve <report-id> --resolution "not hosted on Pushleft"
pushleft-api abuse suspend <report-id> --reason "confirmed phishing" # suspends the org, then resolves
When you resolve a report, Pushleft writes an abuse_report_resolved event to the organization’s audit trail. The event has the category and the resolution, but not the reporter. Set up the abuse@ mailbox as described in operations.
Customer mail quotas
Mail quotas protect the platform’s sending reputation. The customer-mail service calls these functions in PostgreSQL, through its own mail_* functions (migration 0054):
SELECT allowed, reason FROM mail_send_allowed(org); -- before every send
SELECT record_mail_event(org, message_id, 'sent'); -- per accepted recipient (also meters mail_messages)
SELECT record_mail_event(org, message_id, 'bounced'); -- from bounce processing
SELECT record_mail_event(org, message_id, 'complained'); -- from feedback loops
mail_send_allowed returns (false, reason) for these reasons, checked in this order:
unknown_orgorg_suspendedbudget_exceeded(a spent hard-stop budget,org_spend_blocked)mail_pausedmail_quota(sends in the last 24 h have reached the tier’smail_per_day)
Automatic pause. Pushleft pauses mail when, over a rolling 24 hours with at least 100 messages sent:
- more than 5% of the messages bounced, or
- more than 0.1% caused complaints.
The check runs on every bounce or complaint and on every mail_send_allowed call. A pause sets organizations.mail_paused_at and the reason. It writes an org_mail_paused audit event (operator automatic). The pause stays until an operator ends it:
pushleft-api org mail-unpause <org-id> --reason "list cleaned, double opt-in added"
After an unpause, the rates count only mail sent after the unpause. Old bounces do not pause the organization again at once. The thresholds are constants in migration 0052. See also bounces and complaints.
Audit trail
Every operator action writes an auth_events row for the organization. The detail contains operator and reason. The events are:
org_tier_changed,org_suspended,org_unsuspended.org_mail_paused,org_mail_unpaused.org_role_resources_changedandabuse_report_resolved.budget_changedfor budget changes andbudget_threshold_reachedfor budget alerts.
All of them appear in pushleft-api audit --org <id> (operations). The organization’s owners and admins can read them through RLS. A change that is already in effect (for example, suspending an organization that is already suspended) writes no event and prints "changed": false.
Related
- Usage, prices and budgets: meters, budgets and the hard stop.
- Mail: customer mail limits and the log.
- Operations: the
abuse@mailbox and the audit trail. - Security incident runbook: what to do after a confirmed incident.
- Authentication: sign-in and organization access.