gigafibre-fsm/scripts/campaigns/README.md

Gift Campaign — Personalized French email sender

One-shot tool to send Giftbit gift cards to a list of contacts with a branded French email, bypassing Giftbit's English-only built-in delivery.

How it works

1. You generate the gifts in Giftbit (UI or API) and export/receive a CSV containing one gift_url per recipient (one of the standard Giftbit column names: gift_url, gift_link, url, link, redemption_url).
2. You produce a CSV of contacts with columns firstname, lastname, email, description. The repo has a Python helper for this — see how giftbit-contacts-A-first-email.csv was generated.
3. This script matches the two CSVs (by row order, the default) and sends one personalized French email per recipient via Mailjet SMTP.
4. A results-<timestamp>.csv is written next to the script with per-row status (sent / failed / dry-run), error message, and timestamp.

The Giftbit redemption landing page (where the recipient picks a brand) is controlled by Giftbit — set the campaign language to fr-CA in their UI or via their API so the page itself is French.

Setup

cd scripts/campaigns
npm init -y                 # one-time, creates package.json
npm install nodemailer      # the only dependency

Dry run (no emails sent, HTML written for preview)

node send_gift_campaign.js \
  --gifts    /path/to/giftbit-gifts.csv \
  --contacts /path/to/giftbit-contacts-A-first-email.csv \
  --template ./templates/gift-email-fr.html \
  --subject  "🎁 Un cadeau pour vous, de la part de Gigafibre" \
  --amount   "50 $" \
  --expiry   "31 décembre 2026" \
  --from     "Gigafibre <noreply@gigafibre.ca>" \
  --dry-run

A preview-YYYY-MM-DD-HH-MM/ directory will be created with one HTML file per recipient (numbered + email-suffixed). Open a few in a browser to validate the rendering on real data, then drop the --dry-run flag to actually send.

Live send

# Pull SMTP creds from the hub env (same Mailjet account as ERPNext)
source <(ssh root@96.125.196.67 'grep -E "^SMTP_" /opt/targo-hub/.env' | sed 's/^/export /')

node send_gift_campaign.js \
  --gifts    /path/to/giftbit-gifts.csv \
  --contacts /path/to/giftbit-contacts-A-first-email.csv \
  --template ./templates/gift-email-fr.html \
  --subject  "🎁 Un cadeau pour vous, de la part de Gigafibre" \
  --amount   "50 $" \
  --expiry   "31 décembre 2026" \
  --from     "Gigafibre <noreply@gigafibre.ca>" \
  --smtp-host in-v3.mailjet.com --smtp-port 587 \
  --smtp-user "$SMTP_USER" --smtp-pass "$SMTP_PASS" \
  --throttle-ms 600

--throttle-ms 600 = roughly 100 emails/minute, safely below the Mailjet free-plan ceiling of ~120/min. Adjust upward to 250 ms if you're on a paid Mailjet plan.

Matching strategies

--match-by	Behaviour
row (default)	Line N of the gifts CSV pairs with line N of the contacts CSV. Use when Giftbit issued the gifts in the same order as your contacts.
email	Join by email column present in both CSVs. Use when Giftbit included emails in their export (more robust to ordering mistakes).

Template variables

The HTML template at templates/gift-email-fr.html uses {{var}} syntax. Variables resolved at send time:

Variable	Source
{{firstname}}	contacts CSV firstname column (falls back to "cher client")
{{lastname}}	contacts CSV lastname
{{email}}	contacts CSV email
{{description}}	contacts CSV description (we put the service address there)
{{gift_url}}	matched from the gifts CSV
{{amount}}	--amount CLI flag (e.g. "50 $")
{{expiry}}	--expiry CLI flag (e.g. "31 décembre 2026")

The template uses a vintage {{#expiry}} ... {{/expiry}} block for the optional expiry line — currently rendered as plain text (the script's simple {{var}} renderer doesn't strip the tags). If you don't want the expiry sentence, edit the template directly to remove that block.

Source data — the two CSVs

Contacts (what we send to)

Generated from a service-address selection by scripts/campaigns/contacts_from_legacy.py (or by hand). One row per recipient:

firstname,lastname,email,description
Marc-André,Boileau,boileau.marcandre@gmail.com,15 Rue des Hirondelles
Maryse,Roy,roy.maryse@hotmail.com,32 Rue des Hirondelles

Gifts (output from Giftbit)

Whatever shape Giftbit gives you. The script auto-detects the URL column from the common naming conventions. Typically:

gift_id,gift_url,amount
gb_abc123,https://app.giftbit.com/g/x7K2N9...,5000
gb_def456,https://app.giftbit.com/g/p2H8M4...,5000

After sending

Check results-<timestamp>.csv:

• status=sent rows landed in Mailjet's outbound queue (delivery to the recipient's mailbox is not guaranteed — see Mailjet console for bounces).
• status=failed rows have the SMTP error in the error column. Common causes: malformed email address, hard bounce from a stale legacy email.
• Re-run only the failed rows by filtering the results CSV and feeding it back through the script.

What's NOT in this script (intentional MVP scope)

• No persistence to ERPNext doctype (no Gift Campaign records created)
• No click tracking — the gift_url is included verbatim. Giftbit gives you redemption status via their own API/dashboard.
• No ops UI — pure CLI. If we end up running gift campaigns regularly, wrap this in a services/targo-hub/lib/gift-campaign.js endpoint and add a page in ops. For now, one-shot CLI is sufficient.