Scribble handwritten cards for n8n

Send handwritten cards to US postal addresses from an n8n workflow. Scribble writes each message with a real pen and posts the card.

This is the source package for n8n-nodes-scribble. Version 0.1.1 adds direct AI Agent tool support. npm publication and n8n verification are separate release steps; a local build proves neither.

Operations

There is no delivery-confirmed trigger. A mailed event means the card was handed to the carrier.

Use Scribble with an AI Agent

Connect Scribble Tool to an AI Agent's Tool connection, select the resource and operation, and choose your Scribble API credential. The regular Scribble node remains available for standard workflows. The card event trigger starts workflows and is not an AI tool.

For a first test, select Account → Get Credit Balance. It returns the account's credit balance without sending a card. Use a clear tool description, such as "Read the current Scribble card credit balance." This action needs no model-generated fields.

For Card → Send, keep the approved recipient and message fixed or map them from an approved upstream record. Each accepted send uses one credit and may produce a physical card. There is no dry-run mode. The same request validation, credential handling, and idempotency behavior apply to both the standard node and the AI tool.

Connect an account

Create a key in Scribble integrations, then add a Scribble API credential in n8n. The credential test calls GET /api/v1/me and creates nothing.

Grant only the scopes the workflow needs:

See the API documentation for account setup and authentication.

Example: an approved card queue

Use a spreadsheet row or CRM event to start the workflow. Require an approved message and a complete US postal address before the Scribble Card → Send step. Map name, street, city, state, ZIP code, and the finished message. Map the upstream order or deal ID to Your Reference; include the recipient email when available so Scribble can check email-based do-not-mail entries.

Each accepted send uses one credit and can produce a physical card. Arrival dates are estimates. A message has a 500-character ceiling. Test mapping with a mocked API before turning on a mailing workflow.

The connector derives a stable idempotency key from the exact JSON request, including recipient email. Blank custom keys use this automatic key. Identical retries within the API's 24-hour retention period return the original response. For business events that might recur later, store a processed flag in the source system or check cards by reference before sending.

Contact → Create or Replace matches contacts by Your Record ID. When a record matches, Scribble replaces the supported fields and clears omitted values, including existing address and contact details. Send all fields you want to keep. Without a record ID, each run creates another contact.

If upgrading a locally deployed pre-release connector that used the earlier field-list key format, finish pending retries before upgrading. Its automatic keys differ from the current request-body keys.

Card event triggers

Activating a trigger registers its n8n callback with Scribble. It saves the returned signing secret and verifies each delivery against the original request bytes, including a five-minute timestamp tolerance. Missing or invalid signatures never start a workflow. A deactivation removes the subscription; failed removals retain their endpoint ID for retry.

The trigger returns event_id, event_type, event_created, and the card fields. Use event_id to deduplicate any downstream work: Scribble may retry a delivery, and n8n does not provide transactional exactly-once processing. Keep workflow static data private because it contains the webhook signing secret.

Local development

npm ci
npm test
npm pack --dry-run

Tests compile the package, mock all API calls, and send no cards. The build copies nodes/Scribble/scribble.svg into dist/nodes/Scribble/ and removes the obsolete PNG from earlier builds. Both nodes and the credential use that SVG. The package has no runtime npm dependencies. Packing the package rebuilds it first. Before publication, test installation in a local n8n instance and verify a signed event reaches the trigger with its original raw bytes.

The September 8, 2026 preflight passed the official @n8n/scan-community-package 0.34.0 local source rules with zero errors and three warnings recommending themed icon variants. The icon is a faithful outline trace of Scribble's authentic 500×500 public/logos/mark.png, with its original coral mark and opaque cream background. It contains only vector paths and uses the same image on both themes. A 500-pixel render was visually checked against the source; the ink-mask overlap was 99.88%. This local scan does not check npm publication or provenance.

Publish and verify

The package declares an MIT license and Devon Oak LLC as its author. Its repository metadata points to the dedicated public connector repository. Confirm that repository is public and that the npm maintainer has publishing rights before releasing.

The manual release workflow builds the package, runs its offline tests and publishes from GitHub Actions with npm provenance. It runs at the repository root and never sends a card. There is no automatic publication on pushes or pull requests.

For an existing package, configure npm trusted publishing for GitHub owner lukescribbled, repository n8n-nodes-scribble, and workflow filename publish-n8n.yml, allowing direct publication. Then run the workflow with oidc. A brand-new package cannot use settings that exist only after first publication. For version 0.1.0, the workflow also offers first_publish_token: store a short-lived npm publishing token as the repository secret NPM_TOKEN, grant only the access needed to create this package, and configure the token for the account’s non-interactive publishing and 2FA requirements. After the first successful release, configure trusted publishing, revoke the temporary token and remove that secret. Never put a token in source files.

Follow the n8n verification guidelines before requesting n8n Cloud discovery. n8n requires GitHub Actions publication with npm provenance from May 1, 2026. Each release needs registry publication and provenance verification; n8n controls its own review and discovery approval.

Publishing to npm and n8n verification are separate steps. Once the package is published, users of self-hosted n8n can install it through Settings → Community nodes. Cloud discovery requires verification.

Support

Scribble documentation · Contact Scribble

Workflow starters

Three inactive workflow starters cover approved Google Sheets mailing rows, approved Shopify paid orders and approved closed-won HubSpot deals. They use native n8n nodes, keep Send Card disabled and passed 52 fixture cases in n8n's official execution engine without network access. Account setup, real source payload checks and result recording are still required. These files are separate from the existing package tarball.