# Send message

Send a message and save it as a new interaction.

The message is checked against Compliance Guard and may be rejected
if it violates any rules. 

If the message is accepted, it is queued for send. 
You can check the status of the queued interaction by calling 
GET on /interactions/{interactionId} endpoint with the interaction ID
returned by this endpoint.

## Context Variables
### Hydratable Context Variables
Certain context variables can be "hydrated" by this endpoint for use in the template
being rendered for sending. 

For instance, if you provide a loanId in the request
body it is "hydrated" to a loan object and passed to the context. This means you
can then reference things like {{loan.displayId}} when customizing the template.

- companyId hydrates to company
- loanId hydrates to loan
- loanIds hydrates to loans
- caseId hydrates to case

### No Automatic Context Variables
Note that this endpoint does not automatically fill in context variables.

If the template you're sending requires context variables, you must provide them. This
can sometimes be confusing because Peach will automatically calculate and include 
context variables when the system sends a message automatically. See
System Sent Messages for more information.

## Difference from /interactions endpoint
Note this is different from POSTing to a /interactions endpoint because those
endpoints create the interaction object, but do NOT send an actual message. 
(You can think of that endpoint as creating a historical log of an interaction
which happened elsewhere.)

Endpoint: POST /communicator/send
Version: 2023-11-29
Security: oauth2, bearerAuth, apiKeyHeader

## Request fields (application/json):

  - `attachments` (array)
    List of document IDs for documents to attach to the outgoing email.

  - `caseId` (string)
    Mark a particular case as associated with this message.

Hydates to the case context variable for use in the template
being rendered for send.
    Example: "CS-AAAA-BBBB"

  - `channel` (any)
    Specifies the channel(s) to send the message on. 

If an array is provided then the message will be sent to the most appropriate contact
for each specified channel. As long as at least one contact is found, the message
will be sent, if at least one contact could be found then an error will be returned.

  - `contactId` (string)
    The Contact ID of the borrower to which this message should be sent.

If not provided then the system will try to select an appropriate
contact based on the type of message being sent. (e.g., if this
is an email select the primary email address; if this is a
text message select the borrower's mobile phone.)
    Example: "BO-AAAA-BBBB"

  - `context` (any)

  - `interactionExternalId` (string)
    The external ID of the interaction that will be created as a
result of this request. Subsequent attempts to send with the
same external ID will be blocked.

  - `isTransactional` (boolean)
    If true, then sent this interaction as "transactional". 

Transactional interactions are those which are sent via an automated system in response 
to an event or some action taken. e.g., an email sent to confirm a payment was made is transactional;
likewise an email sent to confirm a password change is transacrtional. Examples of
non-transactional messages would be: those sent by an agent in response to a customer request,
for collections, or for marketing.

It's important to mark these messages correctly, because different laws may apply to messages
depending on if they're considered "transactional".

Additionally, a transactional interaction may be sent with different "From:" and "Reply-To:" fields depending on configuration.
The purpose here being that it may be desirable to send messages from an email address
that is clearly marked as "unmonitored", so that recipients do not try to respond
directly to those email addresses.

  - `loanId` (string)
    The ID of a Loan. This marks a particular loan as associated with this interaction.

Hydrates to the loan context variable for use in the template
    Example: "LN-AAAA-BBBB"

  - `loanIds` (array)
    The IDs of several loans. This marks several loans as associated with this interaction.

Hydrates to the loans context variable for use in the template
    Example: ["LN-AAAA-BBBB","LB-CCCC-DDDD"]

  - `overrideRecipient` (string,null)
    The recipient to which this message should be sent. This should be used in special
cases where you cannot create a Contact and use contactId.

WARNING: It is not recommended to use this field. Instead use contactId to specify the contact.

You can only use this field if:
- The interaction channel is email
- A borrowerId is specified
- A previousInteractionId is specified, to an email interaction belonging to that borrower
- That previous interaction was sent "from:" the same email address as the one you want to send to.
Currently only email addresses are supported for this field.

  - `overrideTemplateId` (string,null)
    The template version ID (like TV-AAAA-BBBB) or template descriptor ID (like TD-AAAA-BBBB)
to use.

If a template descriptor is given, then the current template descriptor's activeVersionId is
used.

This should be used in special cases where you do not want to use the implicit template selected 
by the subject and channel fields.
    Example: "TV-AAAA-BBBB"

  - `personId` (string, required)
    The Borrower ID of the borrower to which this message should be sent.

Hydates to the person context variable for use in the template
being rendered for send.
    Example: "BO-AAAA-BBBB"

  - `previousInteractionId` (string)

  - `sendAt` (string)
    This attribute determines when the message should be sent.
If set to null, and the message's timing conflicts with
Compliance Guard's time-of-day restrictions, Communicator
will automatically reschedule it to an allowable time.
If this auto-rescheduling occurs, the sendAt field in the
Interaction response will show the new scheduled time, and
the Interaction status will be marked as scheduled.

To bypass auto-rescheduling, input the current time for
sendAt when calling the endpoint.

Additional Information:
- Regardless of when the message is scheduled to send, its
content will be generated immediately upon calling this endpoint.
- You can manually set a future send time of up to 7 days in the future.

  - `sendJitter` (integer)
    The maximum number of seconds to add to the send time for this communication.
The actual time added will be between 0 and this value.
This is useful for spreading out the delivery
of a large batch of messages over a period of time in order
to avoid delaying other time-sensitive communcations.

  - `statementId` (string)
    Mark a particular statement as associated with this message.
    Example: "SM-AAAA-BBBB"

  - `strictUndefined` (boolean)
    If true an error will be returned if the template contains
a variable that is not defined in the context. For historical
reasons this is false by default, but it is recommended
to set this to true.

  - `subject` (string, required)
    The subject of the interaction. The subject identifies the category of the content
in the message.

Most subjects have an associated implicit theme. e.g., loanOverdueFirstNotice has
a theme of opsCollDebt. For these subjects it is not necessary to specify a theme.

Some subjects like freeForm and custom do not have an implicit theme. When
using these subjects you must specify a theme.

DEPRECATED: locStatementGenerated and locStatementRegenerated are deprecated.
They will be automatically converted into statementGenerated and statementRegenerated
respectively. You should switch to use those subjects directly.

DEPRECATED: failedSettlementPeach is deprecated. This was always a subject used by 
the Peach application internally, and will no longer be used. Attempts to set this
subject will be rejected with a 400 error.
    Enum: "annualPrivacyPolicyNotice", "autopayAgreement", "autopayAmountChanged", "autopayCanceledBySystem", "autopayEnabled", "autopayEnableReminder", "autopayPaymentCanceled", "autopayPaymentMethodUpdated", "autopayPaymentReminder", "autopayPaymentRescheduled", "cardExpiresReminder", "caseEscalation", "ceaseCommunicationAcknowledgement", "ceaseCommunicationRefuseToPay", "confirmationCode", "contactTakeover", "creditNegativeInfoReported", "creditPositiveInfoReported", "custom1", "custom2", "custom3", "custom4", "custom5", "custom6", "custom7", "custom8", "custom9", "custom10", "custom11", "custom12", "custom13", "custom14", "custom15", "custom16", "custom17", "custom18", "custom19", "custom20", "custom21", "custom22", "custom23", "custom24", "custom25", "custom26", "custom27", "custom28", "custom29", "custom30", "custom31", "custom32", "custom33", "custom34", "custom35", "custom36", "custom37", "custom38", "custom39", "custom40", "custom41", "custom42", "custom43", "custom44", "custom45", "custom46", "custom47", "custom48", "custom49", "custom50", "custom51", "custom52", "custom53", "custom54", "custom55", "custom56", "custom57", "custom58", "custom59", "custom60", "custom61", "custom62", "custom63", "custom64", "custom65", "custom66", "custom67", "custom68", "custom69", "custom70", "custom71", "custom72", "custom73", "custom74", "custom75", "custom76", "custom77", "custom78", "custom79", "custom80", "custom81", "custom82", "custom83", "custom84", "custom85", "custom86", "custom87", "custom88", "custom89", "custom90", "custom91", "custom92", "custom93", "custom94", "custom95", "custom96", "custom97", "custom98", "custom99", "custom100", "debtValidationNotice", "debtValidationNoticeArizona", "debtValidationNoticeAutomatic", "debtValidationNoticeNYCYonkers", "debtValidationNoticePuertoRico", "deceasedConfirmationOfPayoff", "deceasedNoticeToRepresentative", "deceasedNotificationUponDeath", "disputeOfDebtConfirmed", "disputeOfDebtSubmitDocumentation", "disputeOfDebtSubmitDocumentationReminder", "disputeOfDebtUnableToConfirm", "disputeOfDebtUnableToResolve", "documentUploadFailed", "downpaymentFailed", "drawFundsDisclosure", "electronicConsentOptOut", "failedSettlementInvestor", "failedSettlementPeach", "freeForm", "freeFormBranded", "futurepayCanceled", "futurepayPaymentDueReminder", "identityTheftIncompleteDocumentation", "identityTheftNotValidated", "identityTheftSubmitDocumentation", "identityTheftSubmitDocumentationFirstReminder", "identityTheftSubmitDocumentationSecondReminder", "identityTheftValidated", "letterReturnedToSender", "loanAccelerated", "loanCanceled", "loanChargedOffUnsecured", "loanDetails", "loanFeeCharged", "loanFreeze", "loanManualPaymentDisclosure", "loanOverdueFifthNotice", "loanOverdueFirstNotice", "loanOverdueFourthNotice", "loanOverdueSecondNotice", "loanOverdueSixthNotice", "loanOverdueThirdNotice", "loanPaidOff", "loanPaymentScheduleChanged", "loanPayoffStatement", "loanRefundProcessed", "loanRightToCurePersonalUnsecured", "loanRightToCurePersonalUnsecuredColorado", "loanRightToCurePersonalUnsecuredDC", "loanRightToCurePersonalUnsecuredIowa", "loanRightToCurePersonalUnsecuredKansas", "loanRightToCurePersonalUnsecuredMaine", "loanRightToCurePersonalUnsecuredMissouri", "loanRightToCurePersonalUnsecuredSouthCarolina", "loanRightToCurePersonalUnsecuredWestVirginia", "loanRightToCurePersonalUnsecuredWisconsin", "loanTermsChangeAgreement", "loanUnfreeze", "locCreditLimitChanged", "locInterestRateChanged", "locLineClosed", "locStatementGenerated", "locStatementRegenerated", "loginFirstPaymentReminder", "microdepositFailed", "microdepositProcessing", "microdepositReminder", "oneTimeCode", "paydayConsumerRightsNotice", "paydayFirstPaymentWithdrawal", "paymentDisputed", "paymentDueDateReminder", "paymentFailed", "paymentMethodAdded", "paymentMethodUpdated", "paymentProcessing", "paymentRescheduled", "paymentReversalFailed", "paymentReversalProcessing", "paymentSuccessful", "payoffStatementDocument", "promiseToPayPeriodKept", "promiseToPayPeriodMissed", "promiseToPayPlanCanceled", "promiseToPayPlanCreated", "promoProgramCanceled", "promoProgramEligibilityAtRisk", "promoProgramExercised", "promoProgramReminder", "reimbursementFailed", "reimbursementProcessed", "reimbursementScheduled", "scraApplicationDenied", "scraBenefitsApplied", "scraBenefitsExpiringNotice", "scraCGFlaggedDocumentRequest", "scraServicemanNotifiedDocumentRequest", "settlementOffer", "settlementOfferFirstReminder", "statement", "statementLOC", "statementGenerated", "statementRegenerated", "unmonitoredEmailAddress", "updateBankAccountConnection"

  - `supercaseBulkOperationId` (string)

  - `theme` (string,null)
    The reason why an interaction occurred.

For example:
- An outbound debt collection call should be marked as opsCollDebt.
- An annual privacy policy update email should be marked as opsServicing.
- A customer service response to borrower's inquiry should be marked as opsServicing.

DEPRECATED: inbBug, inbHumanLove, and opsServicingNegativeCreditReportNotice are deprecated:
you cannot create or update interactions to have these values.
    Enum: "agentNotification", "opsCollDebt", "opsCollLocateBorrower", "opsCollVerifyEmployment", "opsCollContactEmployerNotice", "opsServicingDebtValidation", "opsServicingNegativeCreditReportNotice", "opsServicingTimeBarredNotice", "opsServicing", "opsAccountCredentials", "inbMissingFeature", "inbEducation", "inbBug", "inbRequest", "inbHumanLove", "inbUnknown", "inbOther", "inbServicing", "inbCollections", "inbPayments", "inbFraud", "inbGeneralInquiry"

  - `useTemplate` (boolean)
    Only applicable when channel=mail. If false, will not generate content from a template and will instead
only use the documents referenced in the attachments field.

## Response 409 fields (application/json):

  - `message` (string)


## Response 202 fields