# SendCorrespondenceEmail - Advanced Documentation

## Model Shape (CorrespondenceInfo)

```
Type: "Email" | "Text"                    -- CorrespondenceInfo.CorrespondenceType
Subject: string
Body: string                              -- required message content
ShortMessage: string                      -- DERIVED, do not set (GetPreviewText(Body))
From: CorrespondenceParticipantInfo       -- required; overwritten server-side (see traps)
Tos / CCs / Bccs: CorrespondenceParticipantInfo[]
Claims: {Key:ClaimID, Value:FirmID}[]
Contacts: {Key:ContactID, Value:FirmID}[]
ExternalID: string                        -- required when Action is Reply or Forward

CorrespondenceParticipantInfo:
  Name: string
  Value: string                           -- email address; drives recipient delivery
  Display: string                         -- optional, defaults to Value
```

## Traps

- `Action` is `Controllers.Correspondence.CorrespondenceAction`: `Create`, `Reply`, `Forward`. `Reply`/`Forward` throw `"An ExternalID must be provided in a reply or forward."` if `Correspondence.ExternalID` is blank.
- At least one Claim or Contact is required. Missing both throws `"At least one Claim or Contact is required to send Related Correspondence."`
- Only Claims/Contacts whose FirmID matches the current company are used; others are silently dropped before the check above runs.
- `From` is fully replaced with the authenticated user's identity (Name, Value, Display all overwritten). Whatever `From` you send is discarded.
- `ShortMessage` is derived from `Body` via `GetPreviewText`; do not set it, it is not read from the caller.
- Recipient delivery is driven by `Value` (must be a real email address); `ContactItemType` has no effect on routing.
- Do not confuse `CorrespondenceInfo.Type` ("Email"/"Text") with the unrelated `CorrespondenceType` string parameter on `GetCorrespondencePossibleParticipants` ("Claim"/"Contact") - same name, different concept.

## Script Example

```javascript
async () => {
  const correspondence = {
    Subject: "Case update",
    Body: "<p>Your claim has been updated.</p>",
    Tos: [{ Value: "client@example.com", Name: "Jane Client" }],
    Claims: [{ Key: 12345, Value: 625 }]
  };

  const result = await SecureApi.SendCorrespondenceEmail("process-1", "Create", correspondence);
  return { status: result.Status, id: result.ID };
}
```

## Cross-References

| Need | Use Instead |
|------|-------------|
| Email without claim/contact (not persisted) | `SendEmail(ProcessID, Correspondence)` |
| SMS tied to a claim/contact (persisted) | `SendCorrespondenceSms(ProcessID, Action, Correspondence)` |