Download platform/modules/outreach.py from fsanyoto/loopable: direct link, hf CLI and curl.
- Browser
- Download file 19.2 kB
-
https://huggingface.co/spaces/fsanyoto/loopable/resolve/main/platform/modules/outreach.py
- Command line
-
hf download hf://spaces/fsanyoto/loopable/platform/modules/outreach.py
-
curl -L -o outreach.py https://huggingface.co/spaces/fsanyoto/loopable/resolve/main/platform/modules/outreach.py
19.2 kB
| """Outreach β the internal campaign engine (the HubSpot-parity build, crm-outreach brief v1). | |
| Select a segment of customers β render a personalized template per recipient β queue one | |
| mail.mail each through the ONE sanctioned write path (modules/collections_send.py client: | |
| mail.mail create only, SAFE_MODE allow-list enforced in the data layer) β read outcomes back | |
| from mail.mail state β attribute orders placed within the window to the campaign (the thing | |
| HubSpot can't do: revenue attribution straight off sale.order). | |
| Store keys: | |
| suppression {email_lower: {reason: unsub|bounce|manual, source, at}} | |
| outreach_templates {id: {name, class: marketing|transactional, subject, body_html, ...}} | |
| campaigns {seq, items: {id: {name, template_id, segment, audience[], excluded[], | |
| status draft|queued, scheduled_base, send_log[], sent_at, created_by}}} | |
| Compliance (CAN-SPAM β applies fully to B2B): | |
| - marketing-class sends get the physical-address + unsubscribe footer appended ALWAYS; | |
| - the suppression list is enforced HERE (same choke point as SAFE_MODE), not in the UI; | |
| - unsubscribe v1 = reply-to-unsubscribe (explicitly valid) + List-Unsubscribe mailto header; | |
| - frequency governor: max 1 marketing email per dealer per 7 days across ALL campaigns. | |
| O365 limits: 30 msgs/min β sends are staggered via mail.mail.scheduled_date in 1-min buckets | |
| of 25; 10k recipients/day is far above the dealer book. | |
| """ | |
| import os | |
| import html as _html | |
| import datetime as dt | |
| from jinja2 import Environment, StrictUndefined | |
| import core.store as store | |
| import core.odoo as O | |
| import core.periods as P | |
| import modules.customers as cust | |
| import modules.collections_send as cs | |
| K_SUPP = 'suppression' | |
| K_TPL = 'outreach_templates' | |
| K_CAMP = 'campaigns' | |
| BATCH_PER_MINUTE = 25 # O365 message rate limit is 30/min β stay under it | |
| GOVERNOR_DAYS = 7 # max 1 marketing email per dealer per 7 days | |
| ATTRIB_DAYS = 14 # orders within N days of send count toward the campaign | |
| _env = Environment(undefined=StrictUndefined, autoescape=False) | |
| def _now(): | |
| return dt.datetime.now().strftime('%Y-%m-%d %H:%M') | |
| # ------------------------------------------------------------------ suppression | |
| def suppression(): | |
| return store.get(K_SUPP) or {} | |
| def is_suppressed(email): | |
| return str(email or '').strip().lower() in suppression() | |
| def suppress(email, reason, source, by='?'): | |
| e = str(email or '').strip().lower() | |
| if not e: | |
| return | |
| def _add(d): | |
| d[e] = {'reason': reason, 'source': source, 'by': by, 'at': _now()} | |
| return d | |
| store.update(K_SUPP, _add) | |
| def unsuppress(email): | |
| e = str(email or '').strip().lower() | |
| def _rm(d): | |
| d.pop(e, None) | |
| return d | |
| store.update(K_SUPP, _rm) | |
| # ------------------------------------------------------------------ templates | |
| DEFAULT_TEMPLATES = { | |
| 'reorder-v1': { | |
| 'name': 'Reorder reminder', 'class': 'marketing', | |
| 'subject': 'Time to restock, {{ customer }}?', | |
| 'body_html': ( | |
| '<p>Hi {{ customer }},</p>' | |
| '<p>It has been {{ days_since }} days since your last order with us' | |
| '{% if last_order %} (placed {{ last_order }}){% endif %}; based on your usual ' | |
| 'rhythm, you may be running low.</p>' | |
| '{% if top_skus %}<p>Your recent favorites:</p><ul>' | |
| '{% for s in top_skus %}<li>{{ s }}</li>{% endfor %}</ul>{% endif %}' | |
| '<p>Reply to this email or reach out to {{ agent }} and we will get your next ' | |
| 'order moving.</p>' | |
| '<p>Thank you for your business,<br>{{ company }}</p>'), | |
| }, | |
| 'winback-v1': { | |
| 'name': 'Win-back', 'class': 'marketing', | |
| 'subject': 'We miss you at {{ company }}, {{ customer }}', | |
| 'body_html': ( | |
| '<p>Hi {{ customer }},</p>' | |
| '<p>We noticed your orders have slowed this year and wanted to check in; our new ' | |
| 'catalog has landed and we would love to get you back to the table.</p>' | |
| '<p>Reply to this email or contact {{ agent }} to hear what is new.</p>' | |
| '<p>Thank you,<br>{{ company }}</p>'), | |
| }, | |
| } | |
| def templates(): | |
| t = store.get(K_TPL) or {} | |
| if not t: | |
| stamped = {k: {**v, 'created_by': 'system', 'at': _now()} | |
| for k, v in DEFAULT_TEMPLATES.items()} | |
| try: | |
| store.update(K_TPL, lambda d: (d.update(stamped), d)[1] if not d else d) | |
| t = store.get(K_TPL) or stamped | |
| except Exception: | |
| t = stamped | |
| return t | |
| def save_template(tid, name, tclass, subject, body_html, by='?'): | |
| tid = (tid or name).strip().lower().replace(' ', '-') | |
| def _set(d): | |
| d[tid] = {'name': name, 'class': tclass, 'subject': subject, | |
| 'body_html': body_html, 'created_by': by, 'at': _now()} | |
| return d | |
| store.update(K_TPL, _set) | |
| return tid | |
| def render(subject_tmpl, body_tmpl, ctx): | |
| """StrictUndefined β a missing token fails the PREVIEW, never a live send.""" | |
| return (_env.from_string(subject_tmpl).render(**ctx), | |
| _env.from_string(body_tmpl).render(**ctx)) | |
| # ------------------------------------------------------------------ company footer (CAN-SPAM) | |
| _company_cache = {} | |
| def company_address(): | |
| """Physical postal address for the compliance footer. Env override, else res.company.""" | |
| if 'addr' in _company_cache: | |
| return _company_cache['addr'] | |
| addr = os.environ.get('COMPANY_ADDRESS', '').strip() | |
| if not addr: | |
| try: | |
| rows = O.search_read('res.company', [], ['name', 'street', 'street2', 'city', | |
| 'state_id', 'zip']) | |
| # multi-company instance: take the first company with a real street address | |
| c = next((r for r in rows if r.get('street')), None) | |
| if c: | |
| bits = [c.get('street') or '', c.get('street2') or '', c.get('city') or '', | |
| O.m2o_name(c.get('state_id')), c.get('zip') or ''] | |
| addr = ', '.join(b for b in bits if b) | |
| except Exception: | |
| addr = '' | |
| _company_cache['addr'] = addr | |
| return addr | |
| def marketing_footer(): | |
| addr = company_address() | |
| return (f"<div style='margin-top:24px;padding-top:10px;border-top:1px solid #ECEFF3;" | |
| f"font-size:11px;color:#64748D'>{_html.escape(cs.COMPANY)}" | |
| + (f" Β· {_html.escape(addr)}" if addr else '') | |
| + "<br>You are receiving this because you are a wholesale customer of " | |
| f"{_html.escape(cs.COMPANY)}. To stop receiving these emails, reply with " | |
| "the word <b>unsubscribe</b> and we will remove you within 10 business days." | |
| "</div>") | |
| def wrap_body(inner_html, tclass): | |
| shell = (f"<div style='font-family:Calibri,Arial,sans-serif;color:#1A2332;font-size:14px;" | |
| f"max-width:640px'>{inner_html}" | |
| + (marketing_footer() if tclass == 'marketing' else '') + '</div>') | |
| return shell | |
| # ------------------------------------------------------------------ audiences | |
| SEGMENT_SOURCES = { | |
| 'reorder': 'Reorder due: overdue vs their own cadence', | |
| 'winback': 'Win-back: bought LY, down or gone this year', | |
| 'new': 'New / reactivated this year', | |
| } | |
| def build_audience(source, team_id=None, agent=None, limit=500): | |
| """Segment spec β candidate rows [{pid, customer, metric, agent?}] (active-list semantics: | |
| evaluated NOW; the campaign freezes a snapshot).""" | |
| pids_scope = cust.agent_partner_ids(agent) if agent else None | |
| if source == 'reorder': | |
| rows = cust.contact_recommendations(team_id=team_id, limit=limit, agent_pids=pids_scope) | |
| return [{'pid': r['pid'], 'customer': r['customer'], 'agent': r.get('agent', ''), | |
| 'metric': r.get('overdue_days', 0), 'metric_label': 'days past cadence'} | |
| for r in rows] | |
| if source == 'winback': | |
| rows = cust.at_risk(team_id=team_id, limit=limit, agent_pids=pids_scope) | |
| return [{'pid': r['pid'], 'customer': r['customer'], 'agent': '', | |
| 'metric': r.get('at_risk', 0.0), 'metric_label': 'at-risk $'} for r in rows] | |
| if source == 'new': | |
| rows = cust.new_customers(team_id=team_id, limit=limit, agent_pids=pids_scope) | |
| return [{'pid': r['pid'], 'customer': r['customer'], 'agent': '', | |
| 'metric': r.get('rev_ytd', 0.0), 'metric_label': 'YTD $'} for r in rows] | |
| raise ValueError(f'unknown segment source {source}') | |
| def _partner_info(pids): | |
| """{pid: {email, name, credit}} in one read.""" | |
| if not pids: | |
| return {} | |
| rows = O.search_read('res.partner', [('id', 'in', list(pids))], | |
| ['name', 'email', 'credit']) | |
| return {r['id']: r for r in rows} | |
| def _tokens_bulk(pids, team_id=None): | |
| """Per-recipient template context, pulled in TWO read_groups (never per-recipient calls): | |
| cadence (last order / days since) + top-3 SKUs by LTM revenue.""" | |
| cad = cust._cadence_bulk(team_id=team_id) | |
| lf, lt = P.ltm(P.today()) # ISO strings already (periods convention) | |
| g = O.read_group('sale.order.line', | |
| O.sale_line_domain(lf, lt, team_id, partner_ids=list(pids)), | |
| ['price_subtotal:sum'], ['order_partner_id', 'product_id'], lazy=False) | |
| by_pid = {} | |
| for r in g: | |
| pid = O.m2o_id(r.get('order_partner_id')) | |
| name = O.m2o_name(r.get('product_id')) | |
| if pid and name: | |
| by_pid.setdefault(pid, []).append((r.get('price_subtotal') or 0.0, name)) | |
| top = {pid: [n for _, n in sorted(v, reverse=True)[:3]] for pid, v in by_pid.items()} | |
| out = {} | |
| for pid in pids: | |
| c = cad.get(pid, {}) | |
| out[pid] = {'last_order': c.get('last_order') or '', | |
| 'days_since': int(c.get('days_since') or 0), | |
| 'top_skus': top.get(pid, [])} | |
| return out | |
| def _agent_disp(a): | |
| """Agent token for templates β the '(none)' placeholder must never reach a customer.""" | |
| a = str(a or '').strip() | |
| return a if a and a.lower() != '(none)' else 'your account manager' | |
| def _recent_marketing_sends(): | |
| """{email_lower: last marketing send date iso} across all campaigns β the frequency governor.""" | |
| out = {} | |
| camps = (store.get(K_CAMP) or {}).get('items', {}) | |
| for c in camps.values(): | |
| if c.get('template_class') != 'marketing': | |
| continue | |
| day = (c.get('sent_at') or '')[:10] | |
| if not day: | |
| continue | |
| for s in c.get('send_log', []): | |
| e = str(s.get('email', '')).lower() | |
| if e and (e not in out or out[e] < day): | |
| out[e] = day | |
| return out | |
| # ------------------------------------------------------------------ campaigns | |
| def campaigns(): | |
| d = store.get(K_CAMP) or {} | |
| return d.get('items', {}) | |
| def create_campaign(name, template_id, segment_spec, audience_rows, by='?'): | |
| """Freeze the audience snapshot with exclusions applied UP FRONT (each with its reason β | |
| the excluded rows are shown, never silently dropped): no email / suppressed / marketing | |
| governor (emailed < GOVERNOR_DAYS ago) / duplicate email within the audience.""" | |
| tpl = templates().get(template_id) or {} | |
| tclass = tpl.get('class', 'marketing') | |
| info = _partner_info([r['pid'] for r in audience_rows]) | |
| recent = _recent_marketing_sends() if tclass == 'marketing' else {} | |
| supp = suppression() | |
| cutoff = (dt.date.today() - dt.timedelta(days=GOVERNOR_DAYS)).isoformat() | |
| seen = set() | |
| audience, excluded = [], [] | |
| for r in audience_rows: | |
| p = info.get(r['pid']) or {} | |
| email = str(p.get('email') or '').strip() | |
| el = email.lower() | |
| if not email: | |
| excluded.append({**r, 'reason': 'no email address'}) | |
| elif el in supp: | |
| excluded.append({**r, 'reason': f"suppressed ({supp[el].get('reason', '?')})"}) | |
| elif tclass == 'marketing' and recent.get(el, '') >= cutoff: | |
| excluded.append({**r, 'reason': f'emailed within {GOVERNOR_DAYS}d (governor)'}) | |
| elif el in seen: | |
| excluded.append({**r, 'reason': 'duplicate email in audience'}) | |
| else: | |
| seen.add(el) | |
| audience.append({**r, 'email': email}) | |
| created = {} | |
| def _add(d): | |
| d.setdefault('seq', 0) | |
| d.setdefault('items', {}) | |
| d['seq'] += 1 | |
| cid = f"c{d['seq']}" | |
| d['items'][cid] = { | |
| 'id': cid, 'name': name, 'template_id': template_id, 'template_class': tclass, | |
| 'segment': segment_spec, 'audience': audience, 'excluded': excluded, | |
| 'status': 'draft', 'send_log': [], 'sent_at': None, | |
| 'created_by': by, 'created_at': _now(), | |
| } | |
| created['id'] = cid | |
| return d | |
| store.update(K_CAMP, _add) | |
| return created['id'], len(audience), len(excluded) | |
| def preview_samples(campaign, n=3, team_id=None): | |
| """Render the template for the first n recipients β StrictUndefined surfaces bad tokens | |
| here, at preview time.""" | |
| tpl = templates().get(campaign['template_id']) or {} | |
| aud = campaign['audience'][:n] | |
| toks = _tokens_bulk([r['pid'] for r in aud], team_id) | |
| out = [] | |
| for r in aud: | |
| ctx = {'customer': r['customer'], 'agent': _agent_disp(r.get('agent')), | |
| 'company': cs.COMPANY, 'open_balance': 0.0, **toks.get(r['pid'], {})} | |
| subj, body = render(tpl.get('subject', ''), tpl.get('body_html', ''), ctx) | |
| out.append({'to': r['email'], 'subject': subj, | |
| 'body': wrap_body(body, tpl.get('class', 'marketing'))}) | |
| return out | |
| def send_campaign(cid, base_dt_utc=None, by='?', team_id=None): | |
| """Queue every audience mail (personalized, one mail.mail per recipient, staggered | |
| scheduled_date β€ BATCH_PER_MINUTE/min). SAFE_MODE is checked per recipient HERE: while the | |
| guardrail is ON, non-allow-listed recipients are SKIPPED (logged), so a test send to | |
| yourself works without touching real customers. Returns (queued, skipped).""" | |
| camps = campaigns() | |
| c = camps.get(cid) | |
| if not c or c.get('status') != 'draft': | |
| raise ValueError('campaign missing or already sent') | |
| tpl = templates().get(c['template_id']) or {} | |
| tclass = tpl.get('class', 'marketing') | |
| base = base_dt_utc or dt.datetime.utcnow() | |
| toks = _tokens_bulk([r['pid'] for r in c['audience']], team_id) | |
| info = _partner_info([r['pid'] for r in c['audience']]) | |
| odoo = cs.Odoo() | |
| log = [] | |
| queued = skipped = 0 | |
| for i, r in enumerate(c['audience']): | |
| email = r['email'] | |
| if is_suppressed(email): # re-check at send time | |
| log.append({**r, 'result': 'suppressed'}) | |
| skipped += 1 | |
| continue | |
| if not cs.safe_recipient_ok(email): | |
| log.append({**r, 'result': 'safe-mode-skip'}) | |
| skipped += 1 | |
| continue | |
| ctx = {'customer': r['customer'], 'agent': _agent_disp(r.get('agent')), | |
| 'company': cs.COMPANY, | |
| 'open_balance': float((info.get(r['pid']) or {}).get('credit') or 0.0), | |
| **toks.get(r['pid'], {})} | |
| try: | |
| subj, body = render(tpl.get('subject', ''), tpl.get('body_html', ''), ctx) | |
| when = base + dt.timedelta(minutes=queued // BATCH_PER_MINUTE) | |
| payload = { | |
| 'subject': subj, 'body_html': wrap_body(body, tclass), | |
| 'email_to': email, | |
| 'email_from': cs.SENDER_DISPLAY, 'reply_to': cs.REPLY_TO, | |
| 'mail_server_id': cs.ROYAL_MAIL_SERVER_ID, 'author_id': cs.ROYAL_AUTHOR_ID, | |
| 'state': 'outgoing', 'auto_delete': False, | |
| 'scheduled_date': when.strftime('%Y-%m-%d %H:%M:%S'), | |
| 'model': 'res.partner', 'res_id': r['pid'], # audit trail in chatter | |
| 'headers': repr({'List-Unsubscribe': | |
| f'<mailto:{cs.REPLY_TO}?subject=unsubscribe>'}), | |
| } | |
| mid = odoo.queue_mail(payload) | |
| log.append({**r, 'result': 'queued', 'mail_id': mid, | |
| 'scheduled': when.strftime('%H:%M')}) | |
| queued += 1 | |
| except Exception as e: | |
| log.append({**r, 'result': f'error: {str(e)[:90]}'}) | |
| skipped += 1 | |
| def _fin(d): | |
| item = d.get('items', {}).get(cid) | |
| if item: | |
| item['status'] = 'queued' | |
| item['send_log'] = log | |
| item['sent_at'] = _now() | |
| item['sent_by'] = by | |
| return d | |
| store.update(K_CAMP, _fin) | |
| return queued, skipped | |
| def refresh_outcomes(cid): | |
| """Read mail.mail state back for a campaign's queued mails (sent / exception + reason).""" | |
| c = campaigns().get(cid) or {} | |
| ids = [s['mail_id'] for s in c.get('send_log', []) if s.get('mail_id')] | |
| if not ids: | |
| return {} | |
| rows = O.search_read('mail.mail', [('id', 'in', ids)], | |
| ['state', 'failure_reason']) | |
| by_id = {r['id']: r for r in rows} | |
| def _upd(d): | |
| item = d.get('items', {}).get(cid) | |
| if item: | |
| for s in item.get('send_log', []): | |
| r = by_id.get(s.get('mail_id')) | |
| if r: | |
| s['state'] = r.get('state') | |
| fr = r.get('failure_reason') | |
| if fr: | |
| s['failure'] = str(fr)[:120] | |
| return d | |
| store.update(K_CAMP, _upd) | |
| return by_id | |
| def attribution(cid, days=ATTRIB_DAYS): | |
| """Orders placed by audience customers within `days` of send β per-customer rows + totals. | |
| Correlation window, honestly labeled β not causal ML.""" | |
| c = campaigns().get(cid) or {} | |
| sent = (c.get('sent_at') or '')[:10] | |
| if not sent: | |
| return {'rows': [], 'orders': 0, 'revenue': 0.0, 'window': days, 'from': None, 'to': None} | |
| pids = [r['pid'] for r in c.get('audience', [])] | |
| if not pids: | |
| return {'rows': [], 'orders': 0, 'revenue': 0.0, 'window': days, 'from': sent, 'to': None} | |
| end = (dt.date.fromisoformat(sent) + dt.timedelta(days=days)).isoformat() | |
| g = O.read_group('sale.order', | |
| [('partner_id', 'in', pids), ('state', 'in', ['sale', 'done']), | |
| ('date_order', '>=', f'{sent} 00:00:00'), | |
| ('date_order', '<=', f'{end} 23:59:59')], | |
| ['amount_untaxed:sum'], ['partner_id'], lazy=False) | |
| names = {r['pid']: r['customer'] for r in c.get('audience', [])} | |
| rows = [] | |
| for r in g: | |
| pid = O.m2o_id(r.get('partner_id')) | |
| if not pid: | |
| continue | |
| rows.append({'pid': pid, 'customer': names.get(pid) or O.m2o_name(r.get('partner_id')), | |
| 'orders': r.get('__count') or 0, | |
| 'revenue': r.get('amount_untaxed') or 0.0}) | |
| rows.sort(key=lambda x: -x['revenue']) | |
| return {'rows': rows, 'orders': sum(x['orders'] for x in rows), | |
| 'revenue': sum(x['revenue'] for x in rows), 'window': days, | |
| 'from': sent, 'to': end} | |