DKIM2

content/momentum/3/3-api/hooks-core-final-validation.md

@@ -1,13 +1,13 @@
 ---
-lastUpdated: "03/26/2020"
-title: "final_validation"
-description: "final validation This hook is invoked after the normal validation steps void core final validation closure msg ac ctx void closure ec message msg accept construct ac validate context ctx This hook is invoked after the normal validation steps have completed and is the recommended hook point to implement message..."
+lastUpdated: "07/07/2026"
+title: "final_validation / final_validation2"
+description: "final validation This hook is invoked after the normal validation steps and is the recommended hook point to implement message signing prior to spooling. Two variants exist: core_final_validation (void) and core_final_validation2 (returns a status so a signer can fail or tempfail the message)."
 ---
 
 <a name="hooks.core.final_validation"></a> 
 ## Name
 
-final_validation — This hook is invoked after the normal validation steps
+final_validation, final_validation2 — This hook is invoked after the normal validation steps
 
 ## Synopsis
 
@@ -18,13 +18,15 @@ final_validation — This hook is invoked after the normal validation steps
 |   | <var class="pdparam">ac</var>, |   |
 |   | <var class="pdparam">ctx</var>`)`; |   |
 
+| `int **core_final_validation2** (` | <var class="pdparam">closure</var>, |   |
+|   | <var class="pdparam">msg</var>, |   |
+|   | <var class="pdparam">ac</var>, |   |
+|   | <var class="pdparam">ctx</var>`)`; |   |
+
 `void * <var class="pdparam">closure</var>`;
 `ec_message * <var class="pdparam">msg</var>`;
 `accept_construct * <var class="pdparam">ac</var>`;
-`validate_context * <var class="pdparam">ctx</var>`;<a name="idp45851968"></a> 
-## Description
-
-This hook is invoked after the normal validation steps have completed and is the recommended hook point to implement message signing prior to spooling the message to disk and attempting delivery.
+`validate_context * <var class="pdparam">ctx</var>`;<a name="idp45851968"></a>
 
 **<a name="idp45853360"></a> Parameters**
 
@@ -66,11 +68,35 @@ The `validate_context` struct. For documentation of this data structure see [“
 
 **<a name="idp45864272"></a> Return Values**
 
-This hook returns `void`.
+`core_final_validation` returns `void`.
+
+`core_final_validation2` returns an `int` status:
+
+| Value | Constant | Meaning |
+|---|---|---|
+| `0` | `EC_HOOK_CONT` | Success — continue. Use this even after a *non-fatal* failure if you want the message delivered unsigned rather than rejected. |
+| `1` | `EC_HOOK_DONE` | Error — reject the message (permanent failure). |
+| `2` | `EC_HOOK_RETRY` | Temporary error — defer the message; delivery may be retried. |
+
+## Description
+
+This hook is invoked after the normal validation steps have completed and is the recommended hook point to implement message signing prior to spooling the message to disk and attempting delivery.
+
+It fires on **every injection path** — the same point terminates both the SMTP/relay reception sequence and the HTTP/`msg_gen` (transmissions) generation sequence (see [Policy Phases](/momentum/4/4-policy)). This makes it the natural place for signing that must apply regardless of how a message entered Momentum, in contrast to the `validate_data_spool` / `validate_data_spool_each_rcpt` hooks, which are driven only by the SMTP swap-out engine and therefore never fire on the `msg_gen` path.
+
+### final_validation vs. final_validation2
+
+Two variants of this hook exist at the same point:
+
+- **`core_final_validation`** — the original hook. Returns `void`; it cannot signal a result back to the caller, so a failure inside it cannot reject or defer the message.
+- **`core_final_validation2`** — an extended variant that returns an `int` status (see *Return Values* below), letting a caller **fail (reject) or tempfail (retry)** the message when the validation fails.
+
+*Both variants are invoked* at the same point; `core_final_validation2` is called **first**, and if it returns `EC_HOOK_DONE`/`EC_HOOK_RETRY` the message is rejected/deferred before `core_final_validation` runs. Existing `void` signers registered on `core_final_validation` continue to work unchanged. The [`post_final_validation`](/momentum/4/hooks/core-post-final-validation) hook runs after both.
 
 **<a name="idp45865632"></a> Threading**
 
 This hook will be called in any thread.
 
 <a name="idp45866720"></a> 
-## See Also
+
+## See Also