---
title: SAIF.Framework.Mail business rules
summary: Enumerated business rules with per-rule trigger, enforcement, and outcomes.
status: draft
owner: <owner>
last_reviewed: 2026-07-23
library: SAIF.Framework.Mail
reference_type: package
---

# SAIF.Framework.Mail business rules

This page captures business rules enforced by this library.

## BR-001: Mail is always routed through the configured legacy mail service URL

| Field | Value |
| --- | --- |
| **Statement** | Every outbound mail message is routed through the environment-configured legacy mail service URL (`legacyMailServiceUrl`), never a hardcoded/static endpoint at call time. |
| **Trigger** | Any `Send*` function invocation. |
| **Enforcement** | Each function reassigns the SOAP proxy's `.Url` from `AppGlobal.EnvironmentService.GetConfigSetting("legacyMailServiceUrl")` before invoking the SOAP operation — `MailServices.vb:22,80,109,145,167,189,210`. |
| **Outcome** | The SOAP proxy targets the environment-appropriate mail service endpoint rather than the design-time default baked into `app.config`/`My.Settings`. |
| **Source** | SAIF.Framework.Mail\MailServices.vb |

---

## BR-002: HTML body is the default format

| Field | Value |
| --- | --- |
| **Statement** | HTML vs. plain-text body selection is controlled by the `isHtml` parameter, which defaults to `True`. |
| **Trigger** | Caller omits or explicitly supplies `isHtml` when calling `SendMail` or `SendMailWithOptions`. |
| **Enforcement** | `If (isHtml) Then ... m_mailmsg.SendMail(...) Else ... m_mailmsg.SendMailAsText(...)` — `MailServices.vb:24-28`. |
| **Outcome** | The message is sent as HTML by default; plain text is used only when the caller explicitly passes `isHtml:=False`. |
| **Source** | SAIF.Framework.Mail\MailServices.vb |

---

## BR-003: Send operations always report success regardless of actual outcome

| Field | Value |
| --- | --- |
| **Statement** | Send operations always report success (`Return True`) irrespective of the remote SOAP call's actual outcome.* |
| **Trigger** | Any `Send*` function completes without throwing an exception. |
| **Enforcement** | All `Send*` functions unconditionally `Return True` after invoking the SOAP operation and disposing the proxy, e.g. `MailServices.vb:31`. |
| **Outcome** | Callers cannot distinguish a successful send from a silent failure through the return value alone; failures surface only as unhandled exceptions from the SOAP call itself.* |
| **Source** | SAIF.Framework.Mail\MailServices.vb |

---

## BR-004: File handles are always released, but the original exception's stack trace is reset

| Field | Value |
| --- | --- |
| **Statement** | `GetFileAsBytes` always closes the opened `FileStream` even on error, but re-throws the original exception using `Throw ex`, which resets the exception's stack trace rather than preserving it.* |
| **Trigger** | An exception is raised while opening or reading the file inside `GetFileAsBytes`. |
| **Enforcement** | `Catch ex As Exception : Throw ex` paired with `Finally : FS.Close()` — `MailServices.vb:238-242`. |
| **Outcome** | The file handle is not leaked on error, but the caller receives an exception whose original stack trace has been overwritten.* |
| **Source** | SAIF.Framework.Mail\MailServices.vb |

---

## BR-005: A `Nothing` stream input yields a `Nothing` byte array instead of an exception

| Field | Value |
| --- | --- |
| **Statement** | `GetStreamAsBytes` returns `Nothing` for a `Nothing` input stream rather than throwing an exception. |
| **Trigger** | `inStream Is Nothing` when `GetStreamAsBytes` is called. |
| **Enforcement** | Byte array is only populated `If Not inStream Is Nothing` — `MailServices.vb:257-261`. |
| **Outcome** | A `NullReferenceException` is avoided; the downstream attachment call may receive a `Nothing` byte array.* |
| **Source** | SAIF.Framework.Mail\MailServices.vb |

## Related documentation
- [Index](index.md)
- [Overview](overview.md)
- [Architecture](architecture.md)
- [Dependencies](dependencies.md)
- [Operations and processes](operations-processes.md)
- [Configuration](configuration.md)
- [API reference](api/index.md)

> **Note:** Statements marked with * were inferred from code structure, naming conventions, or
> contextual evidence where direct confirmation was not available in source artifacts. Statements
> marked with ** could not be confirmed; treat as unknown until verified.

## Sources
- SAIF.Framework.Mail\MailServices.vb