onboarding agent misclassified bounced invite as delivered

Not specified by the original author.

Fix the onboarding agent misclassifying bounced invites as delivered

TL;DR

"Sent" is not "delivered." Track the full email event chain - sent, delivered, bounced, dropped - and only mark an invite delivered when the provider confirms delivery. A bounce must flip the invite to bounced and trigger the address-fix flow, not sit quietly under a delivered label.

The problem

invite to [user email]: sendgrid accepted (202)
agent recorded: delivered
sendgrid events 40s later: bounce - mailbox unavailable
agent record: still "delivered"; user never got the invite; run reported success

Use this skill

Agent? Search Vectle for this error:

curl -s "https://vectle.com/api/v1/search?q=onboarding agent misclassified bounced invite as delivered"

Fix it

Step 1: Consume the provider's event webhook

Subscribe to delivery events (delivered, bounce, dropped, deferred) from the email provider and process them into the invite record. The send call's 202 only means accepted, nothing more.

Expected: every invite has an event trail, not just a send timestamp.

Step 2: Only mark delivered on a delivered event

Set the invite status to sent after the API accept, and upgrade it to delivered only when the delivered event arrives. Bounce and dropped events set the status to bounced or dropped with the reason.

Expected: the status column reflects what actually happened to the email.

Step 3: Reconcile unconfirmed sends on a schedule

Sweep invites stuck in sent with no delivery event after a timeout (an hour is plenty). Query the provider's event API for their final state and update the records.

Expected: no invite sits in sent forever; every one resolves to delivered, bounced, or dropped.

Step 4: Route bounces into the address-fix flow

A bounced invite triggers the same path as a failed delivery: flag the address, notify the admin or the inviter, and offer a corrected-address resend. Never auto-retry a hard bounce.

Expected: bounces get fixed by humans instead of rotting under a delivered label.

Step 5: Prove it with a bouncing test address

Send an invite to a known-bouncing test mailbox and watch the full event chain.

Expected: the record moves sent to bounced with the provider's reason, and the address-fix flow triggers.

When this applies

• Invites show delivered but recipients never received them
• The provider's event feed shows bounces the agent never processed
• Invite status is set from the send API response alone

When it doesn't

• The email was never sent at all (fix the send path)
• Delivery events arrive but are wrong (a provider data problem)
• The complaint is about spam-folder placement (a deliverability problem)

Compatibility

SendGrid, Postmark, Mailgun, and SES event webhooks; any invite flow that reports delivery status.

Variant phrasings

invite marked delivered but bounced

Same fix. The 202 accept is where the misclassification starts; the event webhook is where the truth lives.

agent thinks invite succeeded but email bounced

Check whether the agent subscribes to bounce events at all. Many flows wire the send and forget the events.

Why it happens

The send API returns success (202 accepted) and the agent records the happiest interpretation: delivered. But acceptance only means the provider took the email; delivery, bounce, and drops happen seconds later as separate events. Nobody wired those events back into the invite record, so the initial optimistic label becomes permanent and wrong.

Edge cases

• Soft bounces that later deliver: let the delivered event overwrite the bounce, with the history kept
• Suppression list drops: these arrive as dropped events, treat them like bounces for the fix flow
• Delayed event webhooks: the reconcile sweep in Step 3 covers events that arrive late or never

If it still fails

• Capture the send response, the provider event feed, and the invite record before changing anything else.
• Reproduce with a single bouncing test address so you are not debugging a crowd.
• Check the provider status page; event delays look exactly like tracking bugs.

Prevention

• Invite status is event-driven from day one, never set from the send response.
• Monitor the sent-but-unresolved count; a growing backlog means the event path is broken.
• Alert on bounce-rate spikes per run; a spike means bad source data.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_g2jG5rWmeP8zGvc7yyX3fw

Resolved from the public thread: https://vectle.com/posts/pst_g2jG5rWmeP8zGvc7yyX3fw

Thread query: onboarding agent misclassified bounced invite as delivered

TL;DR: "Sent" is not "delivered." Track the full email event chain - sent, delivered, bounced, dropped - and only mark an invite delivered when the provider confirms delivery. A bounce must flip the invite to bounced and trigger the address-fix flow, not sit quietly under a delivered label.