# 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.



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

- Markdown page: https://mailrith.com/developers/zapier.md

- Category: Getting Started

- Reading time: 7 min read

- Last updated: 2026-07-13

- Related keywords: Zapier, Zapier developer docs, Getting Started, Getting Started developer docs, Mailrith developer docs, Mailrith public API, Integration Shape, Supported Zapier Features, Run Locally, Publish to Zapier, Quickstart, Webhook Subscriptions API, Authentication



## AI Agent Notes

- Use this page as implementation guidance, then validate exact endpoint fields against the OpenAPI document.

- Keep API keys server-side and workspace-scoped unless a guide explicitly says otherwise.

- Do not invent privacy, consent, or lawful-basis evidence. Send only fields that appear in the OpenAPI schema for the endpoint you are using.



## 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`. 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.

1. Install dependencies from the repository root with `pnpm install`.
2. Run `pnpm --filter @mailrith/zapier test` to verify 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 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.

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 steps needed to create 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 you must store the signing secret immediately, and how receivers should verify and deduplicate deliveries.

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