Mail merge API: CSV import to personalized letters

Search for a mail merge API and you will find hosted services charging a monthly fee to guess spreadsheet columns. paperplane's version of that is one small endpoint (POST /v1/csv-map) plus the same order endpoint every single letter already uses (POST /v1/orders) — called once per recipient. No campaign object, no subscription, no minimum volume.

What actually happens

There is no server-side batch job. The flow is two calls, run by your own code:

1. Parse your CSV locally (Papa Parse in the browser importer, or csv.DictReader, pandas, whatever your script already uses).
2. Send the header row and a few sample rows to POST /v1/csv-map. It proposes which column is name, line1, line2, city, state, and zip — using an LLM call when an API key is configured, a deterministic alias match otherwise. It never sees your full recipient list, and you confirm or override the mapping before anything gets mailed.
3. Loop your rows and POST /v1/orders once per recipient, substituting the mapped columns into to. Each call is a complete, independent order — its own price, its own status, its own tracking number if the mail class has one.

A real request

Map the columns once. This is the exact shape /v1/csv-map accepts and returns — nothing invented:

curl -X POST https://paperplane.com/v1/csv-map \
  -H 'Content-Type: application/json' \
  -d '{
    "headers": ["Full Name", "Street", "City", "ST", "ZIP"],
    "samples": [["Ada Lovelace", "1 Analysis Way", "San Francisco", "CA", "94107"]]
  }'

# { "status": "ok",
#   "mapping": { "name": ["Full Name"], "line1": ["Street"],
#                "city": ["City"], "state": ["ST"], "zip": ["ZIP"] },
#   "source": "llm" }

Then loop rows and create one order per recipient, personalizing text yourself per row:

import csv, requests

mapping = {"name": ["Full Name"], "line1": ["Street"],
           "city": ["City"], "state": ["ST"], "zip": ["ZIP"]}

for row in csv.DictReader(open("recipients.csv")):
    body = {
        "mail_class": "first_class",
        "sandbox": True,  # flip to False once the run looks right
        "to": {
            "name": row[mapping["name"][0]],
            "line1": row[mapping["line1"][0]],
            "city": row[mapping["city"][0]],
            "state": row[mapping["state"][0]],
            "zip": row[mapping["zip"][0]],
        },
        "from": {"name": "Acme LLC", "line1": "12 Grove Ave",
                  "city": "Richmond", "state": "VA", "zip": "23221"},
        # your own merge field: build the body text per row before you send it
        "text": f"Hi {row['First Name']}, your renewal is due {row['Renewal Date']}.",
    }
    r = requests.post("https://paperplane.com/v1/orders", json=body)
    print(row[mapping["name"][0]], r.json().get("status"))

Try the letter-send call live

Every row your loop produces is this same call — here it is in curl, Python, and JavaScript, and a button that actually fires it at this site's live POST /v1/orders with sandbox: true, so you can see the real response shape (including a real rate-limit error, if you trip one) before you wire up your own loop.

curl -X POST https://sendpaperplane.com/v1/orders \
  -H 'Content-Type: application/json' \
  -d '{
    "mail_class": "first_class",
    "sandbox": true,
    "text": "Dear Alex,\n\nThis is a real letter sent through an API.",
    "to": {
      "name": "Alex Rivera",
      "line1": "12 Grove Ave",
      "city": "Richmond",
      "state": "VA",
      "zip": "23221"
    },
    "from": {
      "name": "Jordan Lee",
      "line1": "1 Main St",
      "city": "Richmond",
      "state": "VA",
      "zip": "23220"
    }
  }'

What this is not

If your spreadsheet is a few dozen renewal notices, invoices, or welcome letters, this is exactly the shape of tool that fits. If you are trying to run a five-thousand-piece direct-mail campaign, the per-actor caps above will stop you well before row 100 — talk to us about a verified account first, or this is the wrong tool for that job today.

Pricing per letter

Every row in the loop is priced individually, same as a single send — no bulk discount tier exists yet:

Run it in sandbox: true first — every row goes through the full validation and mapping path with nothing actually printed or mailed, so you can catch a bad column mapping before it costs anything.