# 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 shape, local validation, and publish process.



- Human page: https://mailrith.com/developers/zapier

- Category: Getting Started

- Reading time: 7 min read



## What this guide covers

Build, test, and publish the official Mailrith Zapier Platform CLI integration.



## Integration Shape

Mailrith's Zapier integration is a Zapier Platform CLI app stored in `packages/zapier`. It 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`, subscribes instant triggers 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 Surface

The Zapier release mirrors Kit's public Zapier surface where Mailrith has equivalent product concepts: subscriber form, landing page, sequence, tag, unsubscribe, bounce, complaint, and subscriber events; subscriber form/sequence/tag write actions; raw authenticated API requests; and subscriber search.

Keep the first public Zapier version stable. Zapier now checks schema-level breaking changes during promotion, so removing triggers, changing auth type, or making optional inputs required should be treated 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 Zapier's own platform commands for schema validation. The package can point at a staging Mailrith API by setting `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.

1. Install dependencies from the repository root with `pnpm install`.
2. Run `pnpm --filter @mailrith/zapier test` to verify the local request mapping, webhook parsing, and action payloads.
3. Set `MAILRITH_ZAPIER_API_BASE_URL=https://api-stage.mailrith.com` and `MAILRITH_ZAPIER_CLIENT_ID=<client_id>` when testing against stage.
4. Run `pnpm --filter @mailrith/zapier zapier:test` to execute the tests through Zapier's CLI wrapper without remote validation.
5. Run `pnpm --filter @mailrith/zapier zapier:validate` for local schema validation.
6. 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**

```bash
pnpm --filter @mailrith/zapier test
```

**Zapier Platform Validation**

```bash
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 it in the Zap editor, and submit it for Zapier review.

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

After the app is approved, publish user-facing help docs and Zap templates so Mailrith users can discover common workflows quickly.

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

**Zapier Publish Commands**

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



## Related Guides

- [Quickstart](https://mailrith.com/developers/quickstart.md): Start with one workspace API key, one authenticated request, and the generated response envelope. This page covers the minimum needed to go from zero to a working subscriber sync.

- [Webhook Subscriptions API](https://mailrith.com/developers/webhook-subscriptions.md): Webhook subscriptions let external systems receive Mailrith events for syncs, dashboards, fulfillment, and audit trails. This guide explains when to use webhooks, how to manage subscriptions, why the signing secret must be stored immediately, and how receivers should verify and deduplicate deliveries.

- [Authentication](https://mailrith.com/developers/authentication.md): Every protected `v1` request resolves through a workspace-scoped API key. This page covers the header shape, workspace scoping behavior, and authentication failure handling.