# SendCorrespondenceSms - Advanced Documentation

## Model Shape (CorrespondenceInfo)

```
Type: "Email" | "Text"                    -- CorrespondenceInfo.CorrespondenceType
Body: string                              -- required message content; Subject is never read
ShortMessage: string                      -- DERIVED, do not set (Body.GetTextFromHTML().Truncate(255))
From: CorrespondenceParticipantInfo       -- required; Value must be the sending number (see traps)
Tos: CorrespondenceParticipantInfo[]      -- exactly one entry required
Claims: {Key:ClaimID, Value:FirmID}[]
Contacts: {Key:ContactID, Value:FirmID}[]
ExternalID: string                        -- required when Action is Reply or Forward

CorrespondenceParticipantInfo:
  Name: string
  Value: string                           -- phone number; drives recipient delivery
```

## 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.Value` is required and NOT overwritten (unlike Email). Only `ContactItemType`, `ParticipantID`, `ParticipantType`, `Name` are overwritten server-side; the phone number you supply in `Value` is what actually sends. Missing `From.Value` throws `"You must have one and only one Sender for SMS."`
- Exactly one `Tos` entry is required. Zero or multiple throws `"You must have one and only one Recipient for SMS."`
- Empty `Body` throws `"You cannot send an empty message."` If `Body` is non-empty but strips to no text (e.g. an image-only HTML body) with no attachments, it throws `"You cannot send a completely blank message. Please provide text, attachment, or image."`
- `Subject` is not referenced anywhere on the SMS path.
- 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 = {
    Body: "Your appointment is confirmed for tomorrow at 10am.",
    From: { Value: "+15551234567" },
    Tos: [{ Value: "+15559876543", Name: "Jane Client" }],
    Claims: [{ Key: 12345, Value: 625 }]
  };

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

## Cross-References

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