notecardHQ
Blog

Handwritten notes from Salesforce

How to send real handwritten cards from Salesforce with a record-triggered Flow and a small Apex action, for closed-won thank-yous, renewals and other moments your org already tracks.

6 min read

To send handwritten notes from Salesforce, use a record-triggered Flow that calls a small Apex action. The Flow decides when a card goes out, for example when an opportunity is Closed Won. The Apex action posts the contact's name, mailing address and message to the notecardHQ API, using a Named Credential that holds your key. notecardHQ has no AppExchange package, so there is nothing to install. The setup and the complete Apex class are in the Salesforce recipe. This post covers which moments to use and how to adapt the action for each.

How the pieces fit

  • External and named credential. They hold your notecardHQ key and your workspace URL. Salesforce adds the Authorization header to every call, so the key never appears in the Flow or in code.
  • An invocable Apex action. It shows up in Flow Builder as "Send handwritten card (notecardHQ)". It hands the records to a queueable job, because a callout cannot run in the same transaction as the record save that started the flow.
  • A record-triggered flow. It runs on the object and condition you choose and maps the recipient's fields and the message into the action.

Flow's built-in HTTP Callout action can call an API without code, but Salesforce puts request headers in the credential, which means they are the same on every call. notecardHQ needs an Idempotency-Key that is different for each record, so a retry never mails twice. Setting that header per record takes a few lines of Apex. Apex is available on Enterprise, Performance, Unlimited and Developer Editions, and the recipe links Salesforce's documentation for each step.

Closed won: thank the buyer

This is the most common starting point, and it is the example the recipe builds. The flow runs on Opportunity when the stage becomes Closed Won, and it maps the opportunity id, the primary contact's name and mailing address, a two-letter country code and the message. The action's key is salesforce:closed-won: plus the opportunity id, so an opportunity that is reopened and closed again does not get a second card.

Two decisions to make before you turn it on:

  • Who signs it. A card from the account executive who ran the deal reads better than one from "the team". Pass the owner's first name into the text template that builds the message.
  • Who receives it. The economic buyer, the champion, or both. For both, run the action twice with different keys, such as closed-won-buyer: and closed-won-champion:.

Renewals: before and after

A renewal card can do two different jobs. A card after the renewal closes is a thank-you: trigger it from the renewal opportunity reaching Closed Won, exactly like a new deal, with its own key prefix such as salesforce:renewal:. The recipe's class hardcodes the closed-won: prefix, so add an event name variable to the request and build the key from it. A card before the renewal is a reason to stay, and it needs to arrive while the decision is still open, typically 30 to 60 days ahead.

For the second kind, you do not need a flow that waits for the right day. API workspaces can send sendOn with a date, and notecardHQ holds the card and mails it on that date. Add an optional date variable to the Apex request and include it in the body:

@InvocableVariable public Date sendOn;
...
'sendOn' => r.sendOn == null ? null : String.valueOf(r.sendOn)

In the flow, set sendOn to a formula such as the renewal date minus 45 days. The date can be up to 365 days ahead; today or earlier sends the card now. You can create the card as soon as the renewal opportunity exists. It waits with the status scheduled, can be edited, rescheduled or cancelled in the portal until two business days before its date, and is not billed until it is released and mailed. More detail is in how to schedule handwritten cards for birthdays and anniversaries.

Other moments worth a card

  • Onboarding complete. A custom field or a stage on the account that marks go-live.
  • A case you resolved. A high-priority case closing, so a person can thank the customer for their patience. Keep a human in the loop here: trigger it from a checkbox the case owner ticks, not from every closed case.
  • Customer anniversaries. A year since the first contract, scheduled with sendOn from the contract start date.
  • Champions who changed jobs. When a contact's account changes, a card to the new address congratulating them.

Each moment gets its own key prefix and its own message. The B2B sales use case has more examples.

Volume and limits

  • One Apex transaction can make at most 100 callouts. If a data load can close more than 100 opportunities at once, split the list into several jobs, as the recipe notes.
  • Errors are written to the debug log rather than retried. Running the action again for the same record is safe, because the same key never sends twice.
  • The country must reach notecardHQ as a two-letter code. If your org stores it as text, convert it in a formula before the action.
  • US addresses are verified before a note is accepted. An undeliverable one returns a 422, nothing is created, and the record should be flagged for someone to fix.

What to write

The message is written exactly as sent, up to 500 characters including the greeting and the sign-off. Build it in a Flow text template so the fields read naturally once filled in:

  • Closed won: "Hi Sam, thank you for trusting us with this. I know it took real work on your side to get it over the line. I will be with you through the first weeks. Chris"
  • Before renewal: "Hi Sam, it has been a year since we started together, and I wanted to say thank you. If anything should change for year two, call me directly. Morgan"

Preview your own copy in the robot's handwriting with the free handwriting preview, and pick one of the four handwriting styles with writingStyle.

Check it and measure it

Build with a test key first: test notes run the same validation as live ones but are never written, mailed or billed. Once live, API workspaces can fetch a proof image of each card before the robot writes it, and every status change can be sent to a signed webhook. To know whether the cards change renewal rates, set a holdout percentage in the workspace so a random share of records is checked but never mailed, then compare the two groups. See how to measure the ROI of handwritten notes.

What it costs

Cards are all-in, with postage included: $3.25 each in the US at up to 499 a month, $2.95 from 500, $2.35 from 2,500 and $1.95 from 10,000, with no monthly fee. Heavier stock, foil and gifts in the envelope are quoted per campaign; see stationery and campaigns.

Start free with a test key and follow the Salesforce recipe. On HubSpot as well? See send handwritten notes from HubSpot.

Keep reading