Send handwritten notes from HubSpot

To send handwritten notes from HubSpot, build a workflow that enrolls the contact or deal at the moment you want to mark, then add a custom code action that posts the recipient and the message to the notecardHQ API. Custom code actions need Data Hub Professional or Enterprise. Without one of those, run the same request from Zapier. notecardHQ has no app on the HubSpot Marketplace, so there is nothing to install. The step-by-step setup and the full code are in the HubSpot recipe. This post covers the decisions around it.

The short version

1. Pick the trigger. A contact becoming a customer, a deal reaching closed won, or another moment your workflows already track.
2. Add a custom code action. It reads the name and mailing address from the enrolled record and sends one request to POST /api/v1/notes, with your notecardHQ key stored as a HubSpot secret.
3. Give every card a stable key. The Idempotency-Key header is built from the record id and the event, so a retry or a re-enrollment never mails a second card.
4. Test, then go live. Build with a test key, which is never written, mailed or billed, then send one live card to your own address.

Choose the workflow trigger

The trigger decides who gets a card and how often, so settle it before writing any code.

• Contact becomes a customer. A contact-based workflow that enrolls when Lifecycle stage becomes Customer. This sends one card per person, which suits a welcome or first-purchase thank-you. Key it on the contact id: hubspot:customer:51.
• Deal closed won. A deal-based workflow that enrolls when the deal stage becomes closed won. This sends a card per deal, which suits B2B sales teams that thank the buyer on every signed contract. Key it on the deal id: hubspot:deal-won:9876. The code reads the properties of the enrolled record, so make sure the recipient's name and mailing address are available on the deal, or send the card from a contact workflow instead.
• Renewals and milestones. Any enrollment trigger you already use for a renewal, an anniversary or a support case you resolved. One trigger per card keeps the copy specific and the results readable.

Whatever the trigger, add a filter for a complete mailing address. The recipe's code skips records without a first name, street and city rather than guessing, and records the reason in the action's output.

Why a custom code action and not "Send a webhook"

HubSpot's Send a webhook action can post record properties and place one API key in a header. notecardHQ needs two headers: Authorization, and an Idempotency-Key that is different for every record. HubSpot's documentation describes no way to set that second header on the webhook action, and a fixed key would make every record after the first return a 409. A custom code action sets both, and it can decide in code whether a record should get a card at all.

The action runs Node.js. You store the key as a secret named NOTECARDHQ_API_KEY, choose which properties to pass in, and paste the code from the recipe. The request it sends looks like this:

POST https://you.notecardhq.com/api/v1/notes
Authorization: Bearer mos_test_...
Content-Type: application/json
Idempotency-Key: hubspot:customer:51

{
  "externalId": "hubspot:51",
  "recipient": {
    "firstName": "Sam", "lastName": "Lee", "businessName": "Acme",
    "address1": "123 Main St", "city": "Austin",
    "state": "TX", "postalCode": "78701", "country": "US"
  },
  "content": "Hi Sam,\n\nThank you for choosing us. It is a pleasure to work with you.\n\nThe team"
}

Two HubSpot limits matter. A custom code action must finish within 20 seconds, so the recipe gives the API call 15. And when the code throws on a temporary error, HubSpot retries the action for up to three days. Because the key stays the same on every try, a retry returns the original note instead of writing a new one. The recipe links HubSpot's own documentation for each of these points.

When to use Zapier instead

The custom code action is the most direct route, but it is not always the right one.

	Custom code action	Zapier
HubSpot subscription	Data Hub Professional or Enterprise	No Data Hub subscription needed
Other subscription	None	A Zapier plan that includes Webhooks by Zapier
Who maintains it	Someone comfortable editing a little JavaScript	Anyone who builds Zaps
Where the key lives	A HubSpot secret	The Zap's request headers
Logic before sending	Anything you can write in code	Zapier filters and paths

Use Zapier when you are not on Data Hub Professional or Enterprise, when the people who own the workflow do not write code, or when the card needs data from another app as well as HubSpot. The Zap uses a Webhooks by Zapier Custom Request step with the same headers and body, and the Idempotency-Key comes from the HubSpot record id, so a replayed step never sends twice. Make and n8n work the same way if your team already uses them.

What to write

The content field is written exactly as sent, up to 500 characters including the greeting and the sign-off. Build it in the code from HubSpot properties, and keep it to three or four sentences from a named person:

• New customer: "Hi Sam, thank you for choosing us. You will hear from me directly if anything needs your attention, and you can always reach me at the number below. Morgan"
• Closed won: "Hi Sam, thank you for the time your team put into this over the last two months. We start on the 3rd and I will be with you for the first weeks. Chris"
• Renewal: "Hi Sam, thank you for another year together. Your feedback shaped a lot of what we built this year. Morgan"

The pen writes letters, digits and common punctuation, including @ $ & % # + =. Emoji are refused with a 422, and accented letters are written without the accent. To see your own copy in the robot's hand before you wire anything, use the free handwriting preview. More on copy in how to write a handwritten note for customers.

Options worth adding

• Handwriting style. Send writingStyle with one of the four styles, or leave it out for Classic.
• A later mail date. API workspaces can add sendOn with a date, and the card is held and mailed on that day. This suits renewal cards, which work best weeks before the renewal date. See how to schedule handwritten cards.
• A proof per card. API workspaces can fetch a proof image of each card, the exact strokes the robot will write on your design, before it is written.
• A holdout group. Set a holdout percentage in the workspace and a random share of enrolled contacts is checked but never mailed or billed, so you can compare deal velocity or renewal rate between the two groups. The method is in how to measure the ROI of handwritten notes.
• Your own card. Start from a stock design or upload your own front and back in the portal. For foil, debossing or a gift in the envelope, see stationery and campaigns.

What it costs

Each card is all-in, with the card, handwriting, envelope and postage included: $3.25 in the US at up to 499 cards a month, $2.95 from 500, $2.35 from 2,500 and $1.95 from 10,000. There is no monthly fee and no HubSpot app fee, and test notes are never billed. See pricing.

Start free with a test key, then follow the HubSpot recipe. Using Salesforce as well? See handwritten notes from Salesforce.