Zapier

Mailrith's Zapier package maps the public API into OAuth authentication, instant REST Hook triggers, Kit-style subscriber actions, raw authenticated API requests, and subscriber search. This page explains the code structure, local validation, and publishing process.

7 min read

Integration Shape

Mailrith's Zapier integration is a Zapier Platform CLI app stored in packages/zapier. The app uses Mailrith's existing public API instead of adding Zapier-only endpoints.

The Zapier app authenticates with OAuth2 and PKCE, tests the connection through GET /v1/capabilities, creates instant trigger subscriptions through POST /v1/webhook-subscriptions, and removes those subscriptions through DELETE /v1/webhook-subscriptions/{webhook_subscription_id}.

Use OAuth for Zapier so users approve a workspace connection in Mailrith instead of copying long-lived API keys into Zapier.

Package: packages/zapier.
Zapier entrypoint: packages/zapier/src/index.cjs.
Authentication: OAuth2 authorization code with PKCE and delegated Authorization: Bearer <access_token> calls.
Instant triggers: REST Hooks backed by Mailrith developer webhook subscriptions.
Write actions: public v1 subscriber, tag, form, landing page, and sequence endpoints.

Supported Zapier Features

The Zapier release matches Kit's public Zapier features where Mailrith has equivalent product concepts. Supported areas include subscriber form, landing page, sequence, tag, unsubscribe, bounce, complaint, and subscriber events; subscriber form, sequence, and tag write actions; raw authenticated API requests; and subscriber search.

Keep the first public Zapier version stable. Zapier now checks for schema-level breaking changes during promotion. Treat removing triggers, changing the auth type, or changing optional inputs to required inputs as a major-version change.

Triggers: New Form Subscriber, New Landing Page Subscriber, New Sequence Subscriber, Subscriber Updated, Tag Added to Subscriber, New Unsubscribe, Subscriber Bounced, Subscriber Complained, New Subscriber, and Tag Removed from Subscriber.
Actions: Create Subscriber, Update Subscriber, Add Subscriber to Form, Add Subscriber to Sequence, Add Tag to Subscriber, Remove Tag From Subscriber, Remove Subscriber from Sequence, and API Request (Beta).
Searches: Find Subscriber by exact email address.
Hidden dropdown helpers: Form, Landing Page, Tag, and Sequence, used by trigger and action fields.
Webhook event patterns used by Zapier: subscriber.created, subscriber.updated, subscriber.status_changed, form.submitted, and landing_page.submitted.

Run Locally

Use the package unit tests for fast contract checks, and use Zapier's platform commands for schema validation. To point the package at a staging Mailrith API, set MAILRITH_ZAPIER_API_BASE_URL.

Use a dedicated OAuth client for Zapier testing. Do not test with a client that powers a live customer workflow.

Install dependencies from the repository root with pnpm install.
Run pnpm --filter @mailrith/zapier test to verify local request mapping, webhook parsing, and action payloads.
Set MAILRITH_ZAPIER_API_BASE_URL=https://api-stage.mailrith.com and MAILRITH_ZAPIER_CLIENT_ID=<client_id> when testing against stage.
Run pnpm --filter @mailrith/zapier zapier:test to execute the tests through Zapier's CLI wrapper without remote validation.
Run pnpm --filter @mailrith/zapier zapier:validate for local schema validation.
Run pnpm --filter @mailrith/zapier zapier:test:remote and pnpm --filter @mailrith/zapier zapier:validate:remote only from a trusted environment where sending integration metadata to Zapier is allowed.

Focused Local Test

pnpm --filter @mailrith/zapier test

Zapier Platform Validation

MAILRITH_ZAPIER_API_BASE_URL=https://api-stage.mailrith.com \
MAILRITH_ZAPIER_CLIENT_ID=<client_id> \
pnpm --filter @mailrith/zapier zapier:test

pnpm --filter @mailrith/zapier zapier:validate

Publish to Zapier

Publishing happens in Zapier, not in the Mailrith deployment pipeline. A Mailrith maintainer with Zapier developer access must register or link the integration, push a version, test the version in the Zap editor, and submit the version for Zapier review.

Zapier requires working authentication, usable test data for triggers, and clean unsubscribe behavior for REST Hook triggers. Before review, turn a Zap on and confirm Mailrith creates a webhook subscription. Then turn the Zap off and confirm Mailrith removes that subscription.

After Zapier approves the app, publish user-facing help docs and Zap templates so Mailrith users can find common workflows quickly.

Log in with the Zapier developer account that owns the Mailrith integration.
From packages/zapier, register or link the app with zapier-platform register "Mailrith" or zapier-platform link.
Push the integration with pnpm --filter @mailrith/zapier zapier:push.
Open the private Zapier app in the Zap editor and test authentication with a dedicated Mailrith OAuth client.
Create one test Zap for each public trigger and action.
Submit the app for Zapier review from the Zapier Platform UI after the private version works end to end.

Zapier Publish Commands

zapier-platform register "Mailrith"
zapier-platform link
pnpm --filter @mailrith/zapier zapier:push

Need Help Shipping an Integration?

Reach the Mailrith team if you need help planning a sync, validating a webhook flow, or troubleshooting a request.

Contact Mailrith

MCP Server

Pagination