sr_pickup_blast — Programmer's Notes¶

Module version: 17.0.2.0.0 Last updated: 2026-03-15 Primary owner: Dan Dependencies: sr_management, sr_management_fixes, base, contacts, mail, mass_mailing, crm

What This Module Does¶

Mass email system for pickup solicitation. Sends "Do you need a pickup?" emails to customers in call queues. Emails contain "Need Pickup" and "Not right now" buttons with unique tokens. Clicking "Need Pickup" auto-creates a CRM lead and contact note. Tracks response rates per customer and per mailing.

Downstream Dependents¶

None — this is a leaf module.

Key Models¶

Model	Purpose
email.pickup.response	Records customer clicks with token validation, expiration, bot detection
mass.email.wizard	Transient wizard for creating/sending mass emails to queues
pickup.response.alert	Alert rules for low response rates
pickup.reengagement	Auto follow-up campaigns for non-responders
res.partner (inherited)	Adds mailing stats: last_pickup_mailing_date, response count/rate

How Token Flow Works¶

1. CSR opens mass email wizard, selects queue (A/B/C/D)
2. System generates unique token per customer per mailing
3. Email sent with links: /pickup/response/<token>/yes and /pickup/response/<token>/no
4. Customer clicks link:
   - Token validated (not expired, not already used, not bot)
   - "yes" → CRM lead created, contact note added, customer flagged
   - "no" → contact note added only
5. Response tracked with timestamp, response_time_hours computed

Critical Gotchas¶

#1: web.base.url MUST be correct¶

Every server needs web.base.url set to its own URL. If wrong, ALL email links 404. This is the most common deployment issue.

Server	web.base.url
Dev	`http://localhost:1818`
Test 1 (exp)	`https://exp.scottrecycling.com`
Staging (1717)	`http://<server>:1717`
Production	`https://scottrecycling.com`

#2: Conflicts with sr_mass_email_from_filter¶

Both modules define a mass.email.wizard model. They CANNOT coexist. If sr_mass_email_from_filter is installed, UNINSTALL it before installing sr_pickup_blast.

#3: Bot detection¶

The controller checks User-Agent to block automated clicks (Microsoft SafeLinks, Google URL preview, python-requests, curl). If a legitimate email client is being blocked, check the bot detection list in email_pickup_response.py.

#4: Unsubscribe affects ALL Odoo mailings¶

When a customer unsubscribes via pickup blast, they're added to mail.blacklist which blocks ALL Odoo mass mailings. This is by design (CAN-SPAM compliance).

#5: Token isolation per mailing¶

Tokens are scoped to their mailing. Token from Mailing A cannot trigger a response on Mailing B. This prevents stale email clicks from creating duplicate leads.

Cron Jobs¶

Both disabled by default:

Job	Purpose
Response Rate Check	Alerts managers when response rates drop below threshold
Re-engagement Sending	Auto sends follow-up to non-responders

System Parameters¶

Key	Default	Purpose
`web.base.url`	varies	CRITICAL — base URL for email links
`sr_pickup_blast.token_expiration_days`	`90`	Token validity period