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

# Custom integration

> Connect your own software to Mailr with the Developer API to trigger campaigns from your events, receive postcard leads back, and report won deals.

If your CRM isn't one of Mailr's native connections and Zapier can't reach it, your own systems can talk to Mailr directly through the **Mailr Developer API**. Your software tells Mailr when something happened — a job finished, a deal closed, a new contact arrived — and Mailr mails the neighbors around that address.

This page is the non-technical half: what's possible, what it looks like inside Mailr, and what to hand your developer. The technical half lives in the [API Reference](/api-reference/overview).

## What you can do with it

* **Trigger campaigns from your own events.** Your system sends an event with the job's address; a matching automation queues a postcard campaign to that street.
* **Receive leads back.** When someone scans a postcard and fills in the landing page, Mailr can push that lead straight into your software. See [Receive leads](/api-reference/receive-leads).
* **Report won deals.** Send the sale back so revenue attaches to the campaign that mailed that home.

<Note>
  Check [the integrations list](/integrations/overview) first. If your CRM is one of the 14 native connections, connect it there instead — nothing to build, and the same triggers, lead sync and revenue tracking.
</Note>

## Where it shows up in Mailr

There's no tile to click and no key to paste into Mailr. Your API key **is** the connection, and the option appears on its own once your systems have sent at least one real event.

Open **Campaigns → Automations** in [the Mailr app](https://app.getmailr.com), create or edit an automation, and look under **Automation details**, below the CRM trigger options: a row reading **Trigger from your API**. Only the workspace **Owner** can create or edit automations — see [Team & roles](/account/team-and-roles). Open it and the panel explains itself:

> *"Fires the moment your integration posts the event. The postcard mails around the address on the record automatically."*

* **Event** — a dropdown of the events your systems have actually sent, grouped as **Job events**, **Deal events** and **Contact events**. Each line shows a readable name plus your own event name in parentheses, like *Job Completed (job.completed)*. Mailr never invents this list: *"These are the events your integration has sent us."*
* **Refresh events** — pulls the list again after your developer sends something new. Before anything arrives you'll see *"No events received yet — send an event from your integration, then refresh."*
* **Only send a postcard when…** *(optional — all rules must match)* — the same filters as any CRM trigger. Pick a **Property** from the fields your events carried, an operator (equals, contains, is at least, is filled, and so on) and a **Value**. Press **+ Add filter** for more, up to 10 rules.
* A recap line spells the rule out: **Fires when** *your API sends a "Job Completed" event* — only if your filters match, and *"Fires instantly, as soon as your API posts the event."*

The panel also warns that **events without a street address (plus a city or ZIP) are skipped** — no address, no postcard. There's no pipeline or stage to pick here; filter on properties instead.

Everything else about the automation is unchanged: neighbors per install, property filters, card type, template, landing page, follow-up drops, automatic review, your cooldowns and your do-not-mail list all work exactly as they do for a connected CRM. Saved automations show a **Your API** pill on the card instead of a CRM logo. See [Automate campaigns](/campaigns/automations).

## What you and your developer need

<Steps>
  <Step title="Create an API key">
    Go to your **workspace name → Manage account → API keys** and create a key. Only the workspace **Owner** can create keys. Copy it once and hand it over — it isn't shown again.
  </Step>

  <Step title="Hand your developer the API reference">
    Point them at [the API overview](/api-reference/overview) and [Send events](/api-reference/send-events). Nothing else is configured on your side.
  </Step>

  <Step title="Have them send a test that mails nothing">
    The API accepts a test ("dry run") event: it runs every check and reports what would have happened, but writes nothing and mails nothing.
  </Step>

  <Step title="Send one real event, then build the automation">
    A real event is what teaches Mailr your event names. Once it lands, press **Refresh events** in the automation editor and pick it from the **Event** dropdown. Then walk the [go-live checklist](/api-reference/go-live) before pointing real traffic at Mailr.
  </Step>
</Steps>

## Zapier or the API?

| Use                                      | When                                                                                                                                 |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| [Zapier](/integrations/zapier)           | Your CRM has a Zapier connector. No developer, no code, works today.                                                                 |
| [Developer API](/api-reference/overview) | Your software has no Zapier connector, or you run something homegrown and want your own retry and error handling. Needs a developer. |

Both end up in the same place — an automation with your postcard settings — so starting on Zapier and moving later costs you nothing.

## Common questions

<AccordionGroup>
  <Accordion title="What happens to an event that doesn't match any automation?">
    Nothing mails. Mailr accepts the event, tells your system that no automation matched, and creates no campaign. That's normal early on — your first events exist mainly to fill the **Event** dropdown so you can build the automation.
  </Accordion>

  <Accordion title="Can we test without mailing anything?">
    Yes. A test ("dry run") event runs the whole path — matching, filters, address check — and reports what would have happened without creating a campaign or spending credits. One catch: because a test writes nothing, it doesn't add your event to the **Event** dropdown. Send one real event for that.
  </Accordion>

  <Accordion title="If a Mailr lead lands in our system, will it start more mail?">
    Not if your integration sends the lead back the way the API describes. Mailr puts an identifier on every lead it delivers to you; when your event carries that identifier back, Mailr recognizes its own lead and skips it, so a lead Mailr sourced can't make Mailr mail that address's neighbors again. If the identifier isn't sent back, Mailr has no way to tell — [Send events](/api-reference/send-events) shows your developer what to echo.
  </Accordion>

  <Accordion title="Is this the same as the Zapier Custom Campaign Trigger?">
    No. **Custom Campaign Trigger** belongs to the Mailr app for Zapier. **Trigger from your API** is your own software talking to Mailr directly. Pick one per automation.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="API reference" icon="code" href="/api-reference/overview">
    Hand this to your developer — keys, events, leads and revenue.
  </Card>

  <Card title="Send events" icon="zap" href="/api-reference/send-events">
    The event your system sends to start a campaign.
  </Card>

  <Card title="Automate campaigns" icon="workflow" href="/campaigns/automations">
    Build the automation your events will fire.
  </Card>

  <Card title="Contact support" icon="life-buoy" href="/resources/contact-support">
    Not sure which path fits your setup? Ask us.
  </Card>
</CardGroup>