Skip to main content

​
Real-World Example

ABC Collections updates Jane’s pay-term offer during an import. The portal should not send that communication inside the upload screen. Instead, it queues the communication work, checks Jane’s permissions, sends the email and SMS through the configured providers, records communication history, and listens for provider callbacks after delivery. If Jane replies STOP by text, the Twilio inbound SMS webhook should update her opt-out state and cancel scheduled follow-up communications. If SendGrid later reports that a campaign email was delivered or opened, the tracking counts should update without requiring a creditor user to refresh or manually mark anything.

​
Visual Flow

​
What Starts Communication

​
Outbound Delivery

Most automated consumer messages flow through a background delivery process.
  1. The platform identifies the matching communication event.
  2. It loads the consumer, company, sub-account, unsubscribe state, and consumer profile.
  3. It checks whether the consumer has updated communication preferences.
  4. It checks email permission, SMS permission, opt-out state, and valid contact details.
  5. Email content is rendered from the selected template and sent through the configured mailer.
  6. SMS content is rendered from the selected template and sent through Twilio.
  7. Communication history records status, destination, cost, SMS segment count, and source where applicable.

​
SendGrid Email Events

SendGrid posts email event callbacks back to YouNegotiate. The callback handler should:
  • Verify the SendGrid signature when signature validation is enabled.
  • Accept a JSON array of provider events.
  • Use the provider tracking key from campaign_tracking_key or custom_args.campaign_tracking_key.
  • Update campaign tracking for delivered and open events.
  • Update EcoMail Hub / ecoPortal™ campaign tracking when the tracking scope is ecomailhub.
  • Ignore unknown or incomplete events without breaking the whole webhook request.

​
Twilio SMS Webhooks

Twilio sends inbound SMS replies back to YouNegotiate. The inbound callback handler should:
  • Verify the Twilio signature when signature enforcement is enabled.
  • Match the sender phone number to consumer account or consumer profile phone indexes.
  • Treat STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, and QUIT as opt-out messages.
  • Treat START, UNSTOP, and YES as opt-in messages.
  • Create or remove unsubscribe records as needed.
  • Update the consumer profile text permission.
  • Delete scheduled follow-up communications after opt-out.
  • Return a successful response even when the phone number does not match a consumer, so Twilio does not retry a non-actionable message.
Twilio also sends SMS delivery status callbacks. Those callbacks should mark SMS as delivered for campaign tracking when Twilio reports delivery. If the message belongs to EcoMail Hub / ecoPortal™ tracking, the EcoMail Hub / ecoPortal™ SMS recipient tracking should update instead.

​
Campaign Delivery

Campaigns are backgrounded to avoid sending hundreds or thousands of messages in one request.
  • Campaign delivery should keep consumer dispatches bounded in chunks.
  • Each individual email, SMS, or e-letter should be sent through a separate background unit of work.
  • Email campaign sends attach a provider tracking key so SendGrid delivery/open webhooks can update campaign counts.
  • SMS campaign sends include Twilio’s status callback URL so delivered messages can update tracking.

​
Safety Rules

  • Provider webhooks should be throttled and signature-verified.
  • Consumer opt-out must stop future SMS and scheduled follow-up communication.
  • A consumer with updated communication preferences should use the consumer profile contact details.
  • A consumer without updated communication preferences should use the account-level imported contact details unless unsubscribed.
  • Invalid or missing email/phone values should be skipped rather than sent blindly.
  • Delivery/open callbacks should update tracking only when the provider tracking key is present.
  • Webhook handlers should not expose sensitive phone numbers in logs.

​
Account Delivery Notification Eligibility

Account and offer delivery occurs before notification eligibility is evaluated. An eligible consumer may receive a new-account or portal-access notification only through allowed communication methods.
  • Consumer profile preferences and identity-level opt-outs override contact information imported by a creditor.
  • When the consumer has saved communication preferences, delivery uses the permitted profile email and mobile details.
  • When no saved preferences exist, delivery may use valid account-level imported contact details unless that method is opted out.
  • Suppressing email or SMS must not prevent the account itself from appearing in the Consumer Portal.

​
How It Should Work

  • It should send communication from background jobs, not long page requests.
  • It should respect consumer permissions, unsubscribe records, and valid contact checks.
  • It should record communication history for billing and operational review.
  • It should let SendGrid and Twilio update tracking after messages leave the app.
  • It should keep campaign and EcoMail Hub / ecoPortal™ tracking separate.

​
How It Should Not Work

  • It should not send SMS after a consumer opts out.
  • It should not mark messages delivered just because the app attempted to send them.
  • It should not trust provider webhook payloads when signature validation is enabled.
  • It should not let one malformed SendGrid event fail the entire batch.
  • It should not mix EcoMail Hub / ecoPortal™ campaign tracking with creditor campaign tracking.
Last modified on August 13, 2026