mailrows 0.1.0__py3-none-any.whl

mailrows/__init__.py

@@ -0,0 +1,3 @@
+"""mailrows: mail merge from Excel or CSV, one templated email per row, safely."""
+
+__version__ = "0.1.0"

mailrows/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from mailrows.cli import main
+
+sys.exit(main())

mailrows/_starter/config.example.ini

@@ -0,0 +1,87 @@
+; mailrows settings. Copy this file to config.ini and fill it in.
+; config.ini is listed in .gitignore: never commit it.
+;
+; Any value can come from an environment variable instead, named MAILROWS_<SECTION>_<KEY>,
+; for example MAILROWS_SMTP_PASSWORD or MAILROWS_AIRTABLE_TOKEN. The variable wins.
+; Paths are relative to this file's folder.
+
+[input]
+file = events.csv
+; for an .xlsx file with several tabs, the tab to read (default: the first)
+sheet =
+; which columns mean what
+id_column = id
+email_column = email
+; mailrows writes progress here after each email. Leave blank to not touch the file.
+status_column = status
+; rows with any of these empty are skipped
+required_columns = first_name, email
+; for a large .xlsx: save the status column every N emails instead of after each one.
+; The send log is updated after every email either way.
+status_save_every = 1
+
+[template]
+; first line "Subject: ...", then the body. Placeholders look like {first_name}.
+text = template.txt
+; optional HTML version with the same placeholders (leave blank for plain text only)
+html =
+
+[smtp]
+host = smtp.example.com
+port = 587
+; ssl (usually port 465), starttls (usually 587) or none. 'mailrows smtp-check' finds the right one.
+security = starttls
+username = your.name@example.com
+password = CHANGE_ME
+timeout = 30
+
+[sender]
+from_name = Example Community Events
+from_email = events@example.com
+reply_to = hello@example.com
+; optional: a copy of every real (not test) email goes here, invisibly
+bcc =
+; seconds to wait between emails
+delay_seconds = 2
+
+[log]
+; the send log that stops anything going out twice. Keep it with the spreadsheet.
+path = mailrows-log.sqlite3
+
+[status]
+; words written to the status column
+sent = sent
+pending = sent, update pending
+unknown = check: may have been sent
+
+[hooks]
+; things to do after each email, comma separated: airtable, webhook, csv_append. Off by default.
+enabled =
+
+[airtable]
+base_id = appXXXXXXXXXXXXXX
+; table name or ID
+table = Attendees
+; the Airtable field to find the record by, and the spreadsheet column with the same value
+match_field = Ticket ID
+match_column = id
+; personal access token with data.records:read and data.records:write on this base only
+token = CHANGE_ME
+
+[airtable.fields]
+; Airtable field = value. {column} takes the value from the row. Built-ins: {_sent_at}, {_sent_date},
+; {_row_id}, {_recipient}, {_subject}.
+Invite status = Invited
+Invite sent on = {_sent_date}
+
+[webhook]
+url = https://hooks.example.com/mailrows
+; optional header, for example a shared secret
+header_name =
+header_value = CHANGE_ME
+; columns to include in the JSON (default: all)
+columns =
+
+[csv_append]
+path = sent-copy.csv
+columns = id, email, _sent_at

mailrows/_starter/examples/events.csv

@@ -0,0 +1,6 @@
+id,first_name,last_name,email,session,seats,status
+E-1001,Ada,Testperson,ada.testperson@example.com,Morning workshop,1,
+E-1002,Bram,Sampleton,bram.sampleton@example.com,Afternoon talks,2,
+E-1003,Cleo,Placeholder,cleo.placeholder@example.com,Morning workshop,1,
+E-1004,Dev,Fakename,dev.fakename@example,Afternoon talks,1,
+E-1005,Esme,Notreal,esme.notreal@example.com,Evening social,3,

mailrows/_starter/examples/template.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html>
+<body style="font-family: Arial, sans-serif; line-height: 1.5; color: #222;">
+  <p>Hi {first_name},</p>
+  <p>Thanks for signing up for the <strong>Riverside Maker Day</strong> on Saturday 14 March.<br>
+     You're booked into: <strong>{session}</strong> ({seats} seat(s)).</p>
+  <p>Doors open at 9:30. Bring a laptop if you have one; we'll have power strips,
+     coffee and plenty of spare cables.</p>
+  <p>Your booking reference is <code>{id}</code>. If you can't make it, just reply to this email
+     and we'll offer your place to someone on the waiting list.</p>
+  <p>See you there,<br>The Maker Day volunteers</p>
+</body>
+</html>

mailrows/_starter/examples/template.txt

@@ -0,0 +1,14 @@
+Subject: Your place at the Riverside Maker Day, {first_name}
+Hi {first_name},
+
+Thanks for signing up for the Riverside Maker Day on Saturday 14 March.
+You're booked into: {session} ({seats} seat(s)).
+
+Doors open at 9:30. Bring a laptop if you have one; we'll have power strips,
+coffee and plenty of spare cables.
+
+Your booking reference is {id}. If you can't make it, just reply to this email
+and we'll offer your place to someone on the waiting list.
+
+See you there,
+The Maker Day volunteers

mailrows/cli.py

@@ -0,0 +1,153 @@
+"""Command line: mailrows send | smtp-check | resolve | init."""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import smtplib
+import sqlite3
+from pathlib import Path
+
+from mailrows import __version__, run, smtpcheck
+from mailrows.config import ConfigError, load, looks_unset
+from mailrows.table import TableError
+from mailrows.template import TemplateError
+
+STARTER_FILES = {
+    "config.example.ini": "config.ini",
+    "examples/events.csv": "events.csv",
+    "examples/template.txt": "template.txt",
+    "examples/template.html": "template.html",
+}
+
+
+def starter_source() -> Path:
+    """Example files: inside the installed package, or the repository root when run from source."""
+    pkg_dir = Path(__file__).resolve().parent
+    packaged = pkg_dir / "_starter"
+    return packaged if packaged.is_dir() else pkg_dir.parents[1]
+
+
+def cmd_init(args) -> int:
+    dest = Path(args.folder)
+    dest.mkdir(parents=True, exist_ok=True)
+    src = starter_source()
+    made = []
+    for rel, name in STARTER_FILES.items():
+        target = dest / name
+        if target.exists():
+            print(f"  kept     {target} (already exists)")
+            continue
+        shutil.copyfile(src / rel, target)
+        made.append(target)
+        print(f"  created  {target}")
+    gitignore = dest / ".gitignore"
+    if not gitignore.exists():
+        gitignore.write_text("config.ini\n*.sqlite3\n*.sqlite3-journal\n", encoding="utf-8")
+        print(f"  created  {gitignore} (keeps config.ini and the send log out of git)")
+    print("\nNext: open config.ini, fill in the [smtp] and [sender] sections, then run")
+    print(f"  mailrows smtp-check -c {dest / 'config.ini'}")
+    print(f"  mailrows send --dry-run -c {dest / 'config.ini'}")
+    return 0
+
+
+def cmd_send(args) -> int:
+    settings = load(args.config)
+    if args.dry_run:
+        mode = run.DRY
+    elif args.test_to:
+        mode = run.TEST
+    else:
+        mode = run.REAL
+    return run.send_command(settings, mode, test_to=args.test_to or "")
+
+
+def cmd_smtp_check(args) -> int:
+    host, user, password = args.host, args.username, None
+    if args.config and Path(args.config).exists():
+        s = load(args.config)
+        host = host or s.get("smtp", "host", "")
+        user = user if user is not None else s.get("smtp", "username", "")
+        password = s.get("smtp", "password", "")
+    if not host:
+        raise ConfigError("Give a host: --host smtp.example.com, or set [smtp] host in the config file.")
+    user = user or ""
+    if user and (password is None or looks_unset(password)):
+        import getpass
+
+        password = getpass.getpass(f"Password for {user} (not shown, not saved): ")
+    best = smtpcheck.check(host, user, password or "", timeout=args.timeout)
+    return 0 if best else 1
+
+
+def cmd_resolve(args) -> int:
+    return run.resolve_command(load(args.config), args.row_id, was_sent=args.sent)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="mailrows",
+                                description="Mail merge from Excel or CSV: one templated email per row, safely.")
+    p.add_argument("--version", action="version", version=f"mailrows {__version__}")
+    sub = p.add_subparsers(dest="command", required=True, metavar="command")
+
+    def with_config(sp):
+        sp.add_argument("-c", "--config", default="config.ini", help="settings file (default: config.ini)")
+
+    s = sub.add_parser("send", help="check every row, show a preview, then send after you type yes")
+    with_config(s)
+    mode = s.add_mutually_exclusive_group()
+    mode.add_argument("--dry-run", action="store_true", help="render and check everything, send and change nothing")
+    mode.add_argument("--test-to", metavar="ADDRESS",
+                      help="send every email to ADDRESS with [TEST] in the subject; no files or logs change")
+    s.set_defaults(func=cmd_send)
+
+    c = sub.add_parser("smtp-check", help="find the port and security setting that work, without sending")
+    with_config(c)
+    c.add_argument("--host", help="mail server (default: [smtp] host from the config)")
+    c.add_argument("--username", help="login to test (default: [smtp] username)")
+    c.add_argument("--timeout", type=float, default=10, help="seconds to wait per attempt (default 10)")
+    c.set_defaults(func=cmd_smtp_check)
+
+    r = sub.add_parser("resolve", help="after checking your Sent folder, record whether an uncertain email went")
+    with_config(r)
+    r.add_argument("row_id")
+    which = r.add_mutually_exclusive_group(required=True)
+    which.add_argument("--sent", action="store_true", help="it arrived: never send it again")
+    which.add_argument("--not-sent", action="store_true", help="it did not go: send it on the next run")
+    r.set_defaults(func=cmd_resolve)
+
+    i = sub.add_parser("init", help="create a starter folder with a config, a sample sheet and templates")
+    i.add_argument("folder", nargs="?", default=".")
+    i.set_defaults(func=cmd_init)
+    return p
+
+
+def main(argv=None) -> int:
+    run.setup_stdout()
+    args = build_parser().parse_args(argv)
+    try:
+        return args.func(args)
+    except (ConfigError, run.SetupError, TableError, TemplateError, sqlite3.Error,
+            smtplib.SMTPException, OSError, KeyboardInterrupt) as exc:
+        message, code = explain_stop(exc)
+        print("\n" + message)
+        return code
+
+
+def explain_stop(exc: BaseException) -> tuple[str, int]:
+    """A readable line, and the exit code, for whatever ended the run early."""
+    if isinstance(exc, (ConfigError, run.SetupError)):
+        return f"Stopped before sending anything: {exc}", run.EXIT_SETUP
+    if isinstance(exc, smtplib.SMTPAuthenticationError):
+        return ("The mail server refused the username or password. Nothing was sent. "
+                "Run 'mailrows smtp-check' to test the login."), run.EXIT_SETUP
+    if isinstance(exc, sqlite3.Error):
+        return (f"Stopped: the send log couldn't be used ({exc}). If another mailrows run is using the same "
+                "log, wait for it to finish. Nothing already sent will be sent again."), run.EXIT_SETUP
+    if isinstance(exc, (TableError, TemplateError)):
+        return (f"Stopped: {exc}. Every email already sent is in the send log and won't be sent again.",
+                run.EXIT_SETUP)
+    if isinstance(exc, KeyboardInterrupt):
+        return "Stopped. Anything already sent is in the send log and won't be sent again.", 130
+    return (f"Stopped: {exc}. Every email already sent is in the send log and won't be sent again. "
+            "If this is a mail server problem, 'mailrows smtp-check' can help."), run.EXIT_SETUP

mailrows/config.py

@@ -0,0 +1,118 @@
+"""Settings: an INI file, with any value overridable by an environment variable.
+
+Environment variables win over the file. The name is MAILROWS_<SECTION>_<KEY> in capitals,
+with dots and dashes in the section name turned into underscores, for example
+MAILROWS_SMTP_PASSWORD or MAILROWS_AIRTABLE_TOKEN.
+"""
+
+from __future__ import annotations
+
+import configparser
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+class ConfigError(Exception):
+    """A setting is missing or wrong. The message says which and how to fix it."""
+
+
+PLACEHOLDERS = {"change_me", "changeme", "your_password", "your_token", "paste_here"}
+
+
+def env_name(section: str, key: str) -> str:
+    clean = section.replace(".", "_").replace("-", "_")
+    return f"MAILROWS_{clean}_{key}".upper()
+
+
+def looks_unset(value: str) -> bool:
+    """True for an empty value or an obvious placeholder. Only whole-value matches count, so a
+    real password that happens to contain '<' or 'your_' is accepted."""
+    v = value.strip()
+    if not v:
+        return True
+    if v.lower() in PLACEHOLDERS:
+        return True
+    return v.startswith("<") and v.endswith(">")  # e.g. <paste your token here>
+
+
+@dataclass
+class Settings:
+    path: Path
+    parser: configparser.ConfigParser = field(repr=False)
+
+    @property
+    def folder(self) -> Path:
+        return self.path.parent
+
+    def get(self, section: str, key: str, default: str | None = None) -> str:
+        from_env = os.environ.get(env_name(section, key))
+        if from_env is not None:
+            return from_env.strip()
+        if self.parser.has_option(section, key):
+            return self.parser.get(section, key).strip()
+        if default is None:
+            raise ConfigError(
+                f"Missing setting [{section}] {key} in {self.path.name} "
+                f"(or set the environment variable {env_name(section, key)})."
+            )
+        return default
+
+    def secret(self, section: str, key: str) -> str:
+        """A password or token. Must be set, and not left as the example placeholder."""
+        value = self.get(section, key, "")
+        if looks_unset(value):
+            raise ConfigError(
+                f"[{section}] {key} is not set. Put it in {self.path.name} (which must stay out of git) "
+                f"or set the environment variable {env_name(section, key)}."
+            )
+        return value
+
+    def get_int(self, section: str, key: str, default: int) -> int:
+        raw = self.get(section, key, str(default))
+        try:
+            return int(raw)
+        except ValueError:
+            raise ConfigError(f"[{section}] {key} must be a whole number, not '{raw}'.") from None
+
+    def get_float(self, section: str, key: str, default: float) -> float:
+        raw = self.get(section, key, str(default))
+        try:
+            value = float(raw)
+        except ValueError:
+            raise ConfigError(f"[{section}] {key} must be a number, not '{raw}'.") from None
+        if value < 0:
+            raise ConfigError(f"[{section}] {key} can't be negative.")
+        return value
+
+    def get_list(self, section: str, key: str) -> list[str]:
+        raw = self.get(section, key, "")
+        return [part.strip() for part in raw.split(",") if part.strip()]
+
+    def items(self, section: str) -> dict[str, str]:
+        """Every key in a section, in file order, keeping the key's original capitals."""
+        if not self.parser.has_section(section):
+            return {}
+        return {k: self.get(section, k) for k in self.parser.options(section)}
+
+    def resolve(self, value: str) -> Path:
+        """A path from the config, relative to the config file's folder."""
+        p = Path(value).expanduser()
+        return p if p.is_absolute() else (self.folder / p)
+
+
+def load(path: str | Path) -> Settings:
+    path = Path(path)
+    if not path.exists():
+        raise ConfigError(
+            f"Config file {path} not found. Copy config.example.ini to config.ini and fill it in, "
+            "or run 'mailrows init' to create a starter folder."
+        )
+    parser = configparser.ConfigParser(interpolation=None)
+    parser.optionxform = str  # keep field names like "Last emailed" exactly as written
+    try:
+        parser.read(path, encoding="utf-8-sig")
+    except (configparser.Error, UnicodeDecodeError) as exc:
+        first_line = str(exc).strip().splitlines()[0] if str(exc).strip() else type(exc).__name__
+        raise ConfigError(f"{path.name} can't be read: {first_line}") from None
+    return Settings(path=path.resolve(), parser=parser)

mailrows/hooks/__init__.py

@@ -0,0 +1,94 @@
+"""Post-send hooks: something to do for each row after its email has gone.
+
+A hook has two steps:
+
+* prepare(rows) runs before ANY email is sent. It checks that the hook will be able to do
+  its job for each row (for Airtable: that the matching record exists) and returns the
+  rows it can't handle, which are then skipped. Raising HookError stops the whole run.
+* run(row) runs after that row's email was sent. If it raises, the row is marked
+  "sent, update pending" and a later run retries only the hook, never the email.
+
+To add a target, subclass Hook, give it a unique name, and register it in HOOK_TYPES.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from mailrows.config import ConfigError, Settings
+from mailrows.template import fill, placeholders
+
+EXTRA_VALUES = ("_row_id", "_recipient", "_subject", "_sent_at", "_sent_date")
+
+
+class HookError(Exception):
+    """The hook can't run at all (bad token, unknown table...). Nothing will be sent."""
+
+
+@dataclass
+class HookRow:
+    row_id: str
+    values: dict[str, str]
+    recipient: str
+    subject: str
+    sent_at: str = ""
+    scratch: dict = field(default_factory=dict)  # whatever prepare() wants to hand to run()
+
+    def merged(self) -> dict[str, str]:
+        extra = {
+            "_row_id": self.row_id,
+            "_recipient": self.recipient,
+            "_subject": self.subject,
+            "_sent_at": self.sent_at,
+            "_sent_date": self.sent_at[:10],
+        }
+        return {**extra, **self.values}
+
+
+class Hook:
+    name = "hook"
+
+    def __init__(self, settings: Settings):
+        self.settings = settings
+
+    def check_columns(self, columns: list[str]) -> None:
+        """Raise ConfigError if a configured value uses an unknown {column}."""
+
+    def prepare(self, rows: list[HookRow]) -> dict[str, str]:
+        return {}
+
+    def run(self, row: HookRow) -> None:
+        raise NotImplementedError
+
+    def describe(self) -> str:
+        return self.name
+
+
+def check_value_placeholders(where: str, values: dict[str, str], columns: list[str]) -> None:
+    known = set(columns) | set(EXTRA_VALUES)
+    for key, value in values.items():
+        for name in placeholders(value, f"{where} {key}"):
+            if name not in known:
+                raise ConfigError(
+                    f"{where} '{key}' uses {{{name}}}, which is not a spreadsheet column. "
+                    f"Built-in values are {', '.join('{' + v + '}' for v in EXTRA_VALUES)}."
+                )
+
+
+def fill_values(values: dict[str, str], row: HookRow) -> dict[str, str]:
+    merged = row.merged()
+    return {k: fill(v, merged) for k, v in values.items()}
+
+
+def load_hooks(settings: Settings) -> list[Hook]:
+    from mailrows.hooks.airtable import UpdateAirtable
+    from mailrows.hooks.csv_append import CsvAppender
+    from mailrows.hooks.webhook import PostWebhook
+
+    types = {h.name: h for h in (UpdateAirtable, PostWebhook, CsvAppender)}
+    out = []
+    for name in settings.get_list("hooks", "enabled"):
+        if name not in types:
+            raise ConfigError(f"[hooks] enabled lists '{name}'. Known hooks: {', '.join(types)}.")
+        out.append(types[name](settings))
+    return out

mailrows/hooks/airtable.py

@@ -0,0 +1,134 @@
+"""Update one Airtable record per sent email.
+
+Config:
+
+    [airtable]
+    base_id = appXXXXXXXXXXXXXX       ; from the base's API page
+    table = Attendees                 ; table name or ID
+    match_field = Ticket ID           ; Airtable field to look the record up by
+    match_column = id                 ; spreadsheet column holding that value
+    token = ...                       ; or MAILROWS_AIRTABLE_TOKEN
+
+    [airtable.fields]
+    ; Airtable field = value. {column} takes the value from the spreadsheet row.
+    Status = Invited
+    Invite sent = {_sent_date}
+
+Every matching record is found before any email is sent. Calls are kept under 5 per second
+and retried with backoff when Airtable is busy.
+"""
+
+from __future__ import annotations
+
+import urllib.parse
+
+from mailrows.config import ConfigError
+from mailrows.hooks import Hook, HookError, HookRow, check_value_placeholders, fill_values
+from mailrows.hooks.http import HttpError, JsonClient
+from mailrows.table import as_text
+
+LOOKUP_BATCH = 25  # values per lookup request: keeps the URL short
+
+HINTS = {
+    401: "the token was not accepted. Create a new one at airtable.com/create/tokens",
+    403: "the token can't use this base or table. Give it the data.records:read and "
+         "data.records:write scopes and access to this base",
+    404: "the base or table was not found. Check base_id and table under [airtable]",
+    422: "Airtable turned the request down. Check match_field and the names under [airtable.fields]",
+}
+
+
+def quote_formula_string(value: str) -> str:
+    return '"' + value.replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
+class UpdateAirtable(Hook):
+    name = "airtable"
+
+    def __init__(self, settings, sleep=None):
+        super().__init__(settings)
+        s = settings
+        self.base = s.get("airtable", "base_id")
+        self.table = s.get("airtable", "table")
+        self.match_field = s.get("airtable", "match_field")
+        self.match_column = s.get("airtable", "match_column")
+        if any(ch in self.match_field for ch in "{}"):
+            raise ConfigError("[airtable] match_field can't contain { or }.")
+        self.fields = s.items("airtable.fields")
+        if not self.fields:
+            raise ConfigError("[airtable.fields] is empty: list at least one 'Field name = value'.")
+        self.api = s.get("airtable", "api_url", "https://api.airtable.com/v0").rstrip("/")
+        token = s.secret("airtable", "token")
+        extra = {"sleep": sleep} if sleep else {}
+        self.client = JsonClient({"Authorization": f"Bearer {token}"}, per_second=4.5,
+                                 retries=s.get_int("airtable", "retries", 5),
+                                 backoff=s.get_float("airtable", "backoff_seconds", 1.0), **extra)
+
+    def describe(self):
+        names = ", ".join(self.fields)
+        return f"airtable: set {names} on the record whose '{self.match_field}' matches '{self.match_column}'"
+
+    def _url(self, record_id: str = "") -> str:
+        path = f"{self.api}/{urllib.parse.quote(self.base, safe='')}/{urllib.parse.quote(self.table, safe='')}"
+        return f"{path}/{urllib.parse.quote(record_id, safe='')}" if record_id else path
+
+    def _request(self, method: str, url: str, payload=None):
+        try:
+            return self.client.call(method, url, payload)
+        except HttpError as exc:
+            hint = HINTS.get(exc.status or 0)
+            detail = hint or (exc.body[:200] if exc.body else str(exc))
+            raise HookError(f"Airtable: {exc} - {detail}") from None
+
+    def check_columns(self, columns):
+        if self.match_column not in columns:
+            raise ConfigError(f"[airtable] match_column '{self.match_column}' is not a spreadsheet column.")
+        check_value_placeholders("[airtable.fields]", self.fields, columns)
+
+    def prepare(self, rows: list[HookRow]) -> dict[str, str]:
+        wanted: dict[str, list[HookRow]] = {}
+        problems: dict[str, str] = {}
+        for row in rows:
+            value = row.values.get(self.match_column, "").strip()
+            if not value:
+                problems[row.row_id] = f"'{self.match_column}' is empty, so no Airtable record can be matched"
+            else:
+                wanted.setdefault(value, []).append(row)
+        found: dict[str, list[str]] = {v: [] for v in wanted}
+        values = list(wanted)
+        for i in range(0, len(values), LOOKUP_BATCH):
+            chunk = values[i:i + LOOKUP_BATCH]
+            # &'' turns numbers into text, so 101 and "101" both match
+            terms = [f"{{{self.match_field}}}&''={quote_formula_string(v)}" for v in chunk]
+            formula = terms[0] if len(terms) == 1 else "OR(" + ",".join(terms) + ")"
+            offset = None
+            while True:
+                params = [("filterByFormula", formula), ("fields[]", self.match_field), ("pageSize", "100")]
+                if offset:
+                    params.append(("offset", offset))
+                page = self._request("GET", self._url() + "?" + urllib.parse.urlencode(params))
+                for record in page.get("records") or []:
+                    got = (record.get("fields") or {}).get(self.match_field)
+                    if isinstance(got, list):
+                        got = got[0] if got else None
+                    key = as_text(got)
+                    if key in found:
+                        found[key].append(record["id"])
+                offset = page.get("offset") or None
+                if not offset:
+                    break
+        for value, matched in found.items():
+            for row in wanted[value]:
+                if not matched:
+                    problems[row.row_id] = f"no Airtable record has {self.match_field} = {value}"
+                elif len(matched) > 1:
+                    problems[row.row_id] = f"{len(matched)} Airtable records have {self.match_field} = {value}"
+                else:
+                    row.scratch["airtable_id"] = matched[0]
+        return problems
+
+    def run(self, row: HookRow) -> None:
+        record_id = row.scratch.get("airtable_id")
+        if not record_id:
+            raise HookError("the Airtable record was not looked up first")
+        self._request("PATCH", self._url(record_id), {"fields": fill_values(self.fields, row), "typecast": True})