> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getmailr.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Mailr is a direct-mail marketing platform for US home-services contractors. Each postcard is personalized with an AI-enhanced image of the recipient's own home and a unique QR code that leads to a personalized landing page. Campaigns can target a neighborhood the customer draws on a map, the homes around past jobs they upload or import, or fire automatically from their CRM. Mailr does not mail an uploaded recipient list. When answering questions, prefer the exact steps and UI labels from these docs, and direct users to app.getmailr.com to sign in. For anything involving account-specific data, billing disputes, or mail that appears lost, direct the user to support@getmailr.com.

# Housecall Pro

> Connect Housecall Pro to Mailr to trigger postcards from jobs, estimates and invoices, and book revenue when an estimate is approved.

Connecting Housecall Pro lets your jobs and estimates start postcard campaigns around the job address, and credits the money back to the campaign that earned it. Postcard leads flow the other way into Housecall Pro as customers.

## What you get

* **Triggers** — 13 Housecall Pro events can start a campaign: **Job created**, **Job scheduled**, **Job started**, **Job completed**, **Job paid**, **Job canceled**, **Estimate created**, **Estimate sent**, **Estimate approved**, **Invoice created**, **Invoice paid**, **Customer created**, and **Customer updated**. You choose the event on each [automation](/campaigns/automations).
* **Revenue tracking** — revenue books when an **estimate is approved**, using the approved estimate total. Mailr's wizard says it plainly: *"Revenue books when an estimate is approved — when it's sold, not when the job wraps."*
* **Lead delivery** — when someone scans your postcard and fills in the landing page, Mailr creates a customer in Housecall Pro with the lead source **"Mailr"**, and tries to surface the lead in your Leads pipeline. Extra answers from the form go into the customer notes.

## Connect Housecall Pro

<Steps>
  <Step title="In Mailr, open Automations">
    Go to **Campaigns → Automations** in [the Mailr app](https://app.getmailr.com) and find **Housecall Pro** under **CRM Connection**. Clicking a tile only opens its panel — nothing starts connecting until you press the Connect button inside. Only the workspace owner can connect a CRM.
  </Step>

  <Step title="Generate an API key in Housecall Pro">
    In Housecall Pro, go to **My Apps → All Apps → API Key Management** (you need admin access) and generate a key. Mailr's dialog links straight there with an **Open API Key Management** button.
  </Step>

  <Step title="Paste the key in Mailr">
    Press **Connect Housecall Pro** and paste the key. Mailr checks it against your account before saving, so a bad key never saves.
  </Step>
</Steps>

<Check>The tile switches to **Connected** and the 3-step setup wizard opens: **Leads → Job address → Tracking**.</Check>

## How syncing works

Out of the box, Housecall Pro is **checked hourly** — a campaign can be queued up to an hour after the event. Automated campaigns use a design you've already approved and are reviewed by Mailr before anything mails.

### Turn on instant updates (optional, recommended)

Instant updates need the Housecall Pro **MAX plan**. The wizard's Tracking step and a banner on the connected panel walk you through it:

<Steps>
  <Step title="Open Webhooks in Housecall Pro">
    Go to **Housecall Pro → My Apps → Webhooks** and switch the toggle to **Active**.
  </Step>

  <Step title="Paste the webhook URL Mailr shows">
    Mailr displays the URL with a one-click copy button. Paste it into Housecall Pro and save.
  </Step>

  <Step title="Turn on the events">
    Under **Enable Webhook Events**, switch on `job.created`, `job.scheduled`, `job.started`, `job.completed`, `job.paid`, `job.canceled`, `estimate.created`, `estimate.sent`, `estimate.option.approval_status_changed`, `invoice.created`, `invoice.paid`, `customer.created`, and `customer.updated`. Extra events are harmless — Mailr ignores anything else.
  </Step>

  <Step title="Copy the signing secret back into Mailr">
    Copy the signing secret Housecall Pro shows you and paste it into the field in Mailr. Banner copy: *"Optional: add your Housecall Pro webhook signing secret for instant sync — without it, changes arrive with the hourly sweep."*
  </Step>
</Steps>

If instant updates don't arrive, re-copy the secret from **Housecall Pro → My Apps → Webhooks** and paste it in again. The hourly sweep covers everything in the meantime.

<Note>
  The first sync starts the clock the moment you connect. Jobs and estimates that were already approved or completed before you connected will never trigger a campaign. To test, approve a fresh estimate after connecting.
</Note>

## Disconnect or reconnect

Disconnecting shows **"Disconnect Housecall Pro?"**: *"Lead sync and campaign triggers through this connection will stop, and the stored credentials are deleted. Your settings are kept, so reconnecting later picks up where you left off."*

Your campaign history, leads and results stay. Reconnecting keeps your field mappings and attribution window.

<Warning>
  Disconnecting does **not** remove the webhook you set up inside Housecall Pro. If you don't plan to reconnect, switch it off yourself in **My Apps → Webhooks**.
</Warning>

## Notes & limits

* Housecall Pro has **no custom fields**, so extra lead answers are combined into the customer notes, and there's no job-address override in the wizard.
* Leads are matched by email only. A lead with no email address always creates a new customer.
* If you import past work to mail older customers, Mailr looks at your most recently updated completed jobs, or your customers.

Still stuck? See [Troubleshooting connections](/integrations/troubleshooting) or [contact support](/resources/contact-support).