Forwarding Rules API

Forwarding rules are tenant-scoped. Each rule belongs to one receiving route and can forward matching received email to one or more external destination addresses after the inbound MIME message has already been stored. OpenSend records every queued, skipped, or failed forwarding attempt so disabled rules, invalid rules, loop-prevention blocks, and send-boundary failures remain auditable.

List forwarding rules

GET /api/receiving/forwarding-rules

Optional query parameters:

The response includes each rule and its latest forwarding attempt when one exists.

{
  "object": "list",
  "data": [
    {
      "object": "forwarding_rule",
      "id": "rule-id",
      "domain_id": "domain-id",
      "domain": "inbound.example.com",
      "route_id": "route-id",
      "route_target_address": "support@inbound.example.com",
      "destinations": ["ops@example.net"],
      "status": "active",
      "invalid_reason": null,
      "last_attempt": null
    }
  ]
}

Create a forwarding rule

POST /api/receiving/forwarding-rules

{
  "route_id": "route-id",
  "destinations": ["ops@example.net", "archive@example.net"],
  "status": "active"
}

destinations must contain 1 to 25 valid email addresses. OpenSend normalizes and deduplicates addresses. Active rules cannot point back to the same receiving domain or matched receiving address; loop-prevention violations return 422 and are not activated. Use status: "disabled" when you want to save a rule without forwarding future inbound messages yet.

Update a forwarding rule

PATCH /api/receiving/forwarding-rules/{id}

{
  "destinations": ["new-ops@example.net"],
  "status": "disabled"
}

Only active and disabled are client-settable statuses. OpenSend may surface invalid for rules that are no longer safe to run. Disabled or invalid rules do not delete received email; matching inbound messages create skipped forwarding attempts with an explanatory reason.

Delete a forwarding rule

DELETE /api/receiving/forwarding-rules/{id}

{
  "object": "forwarding_rule",
  "id": "rule-id",
  "deleted": true
}

Forwarding attempts

When inbound ingestion stores a received email and its route decision matches an active forwarding rule, OpenSend creates a new outbound email through the existing send queue boundary and writes a forwarding_attempts row linked to the received email, rule, tenant, destinations, and forwarded outbound email ID.

Attempt statuses: