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 SendGrid reports that Jane’s email bounced, the platform records the reason and blocks future email to that address for Jane’s ecoAddress across her creditor accounts. Jane can still receive messages at another eligible contact. If she repliesSTOP by text, the block applies to the phone number, including when another consumer uses it.
Visual Flow
What Starts Communication
Outbound Delivery
Most automated consumer messages flow through a background delivery process.- The platform identifies the matching communication event.
- It loads the consumer, company, sub-account, unsubscribe state, and consumer profile.
- It checks whether the consumer has updated communication preferences.
- It checks email permission, SMS permission, opt-out state, and valid contact details.
- Email content is rendered from the selected template and sent through the configured mailer.
- SMS content is rendered from the selected template and sent through Twilio.
- 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_keyorcustom_args.campaign_tracking_key. - Update campaign tracking for
deliveredandopenevents. - Update EcoMail Hub / ecoPortal™ campaign tracking when the tracking scope is
ecomailhub. - Ignore unknown or incomplete events without breaking the whole webhook request.
- A
bounce,blocked, orspamreportevent restricts the email address on the original communication for the associated ecoAddress. This includes blocked messages reported as abouncewith typeblocked. - A
droppedevent is recorded in delivery history and does not add a contact restriction.
Resend Email Events on Staging
Production email uses SendGrid. Staging email uses Resend for both mailers. A signed Resend bounce blocks future email to the address on the original send for that consumer’s ecoAddress. The callback must identify a single recipient that matches the recorded address. Other email addresses and other ecoAddresses remain eligible. The same restriction applies to queued messages before they are sent. Later delivery events leave the restriction in effect.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.
- Block the sender’s phone number for consumer SMS when it receives a STOP keyword, including numbers that have no linked account yet.
- Lift the destination block on
STARTorUNSTOP. Personal contact restrictions and channel preferences still apply.
failed or undelivered event restricts the number on the original communication for that ecoAddress. A canceled event is recorded in delivery history and does not add a contact restriction. SMS START lifts only the destination block created by an inbound STOP.
For qualifying failures, the platform records the provider event, reason or code, and timestamp. Repeated callbacks reuse the existing restriction. Later delivery updates leave the restriction in effect. Charges already on an invoice remain on that invoice.
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.
- Contact opt-outs apply to the affected ecoAddress and contact. An inbound SMS STOP applies to the entire destination number.
- 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 and open callbacks use tracking information captured on the original send.
- 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.
- If an Add or Add + CFPB row uses a contact the consumer previously opted out of, the valid account and offer still reach New Offers and the existing import alert suppression applies. A provider-failure restriction is checked when a notification is sent and blocks only the affected contact.
- 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.

