Direct mail API for Bubble
Direct mail API for Bubble: add Mailr to the API Connector once, with the key in a private header, then call it from a backend workflow when a user signs up, a form is saved or an order comes in. Mailr prints the postcard or letter and mails it, and the workflow saves the piece's id on the record so nobody gets mailed twice.
What to mail from Bubble
| When this happens | Mail this |
|---|---|
| A user signs up (Schedule API Workflow, 3 days later) | A founder welcome letter. (Welcome letter) |
| A database trigger event: an Order changes to paid, and it is the customer's first | A thank-you postcard with a code for the next order. (First-order thank you) |
| A Lead is created from a request form on a page | A postcard in your own design to the address on the form. |
Set it up
- Add the API Connector. In the Plugins tab, add the API Connector by Bubble. Create a collection named Mailr and set Authentication to Private key in header: Key name Authorization, Private key Bearer mlr_live_…, Development key value Bearer mlr_test_…. The development version of your app then uses the free test key and the live app uses the live one. Add Content-Type: application/json under Shared headers for all calls.
- Add the call. Add a call named Send welcome letter: Use as Action, POST https://api.mailr.dev/v1/flats, JSON body as in the second tab. To initialize, fill the parameters with your own name and address, a two-letter state and a 5-digit ZIP; an empty line2 is fine. Uncheck Private on each <parameter> you'll fill from the workflow, and add an Idempotency-Key header with Private unchecked so each run can set its own value. Check Include errors in response & allow workflow actions to continue.
- Initialize it with your own address. Initialize call sends a real request; it isn't a simulation. In development it uses the test key, so the letter is free and never prints, and it shows up in your Mailr dashboard.
- Build the backend workflow. In Settings > API, check Enable Workflow API and backend workflows. On the Backend workflows page, add send-welcome-letter with a user parameter, run the Mailr call, then save the returned id on the user (third tab).
- Schedule it from signup. In the signup workflow, after Sign the user up, add Schedule API Workflow: send-welcome-letter, Scheduled date Current date/time +(days): 3, user = Current User. Save a return address in Mailr Settings so the body can leave out from. Deploy to live when the test letters look right.
The API Connector call and the workflow
API Collection: Mailr
Authentication: Private key in header
Key name: Authorization
Private key: Bearer mlr_live_... (the live app)
Development key value: Bearer mlr_test_... (version-test: free, never prints)
Shared headers for all calls:
Content-Type: application/json
Call: Send welcome letter
Use as: Action
Data type: JSON
POST https://api.mailr.dev/v1/flats
Headers:
Idempotency-Key: init-1 Private: unchecked (set per run in the workflow)
Body type: JSON (second tab)
Include errors in response & allow workflow actions to continue: checked- API Connector calls go through Bubble's server, so the key never reaches the user's device. Bubble does send a description of each call to the browser, which is why the key belongs in Private key in header: Bubble's docs warn that in a collection set to None or self-handled, values marked Private can be read by anyone.
- The Idempotency-Key header isn't a secret, so leaving it unchecked is fine. Built from the user's unique id, it means a re-run within 24 hours returns the first letter instead of printing a second, and the Only when check on mailr_letter_id covers anything later.
- Run the call from a backend workflow, not a page workflow. It can wait three days, runs whether or not the user still has the page open, and its errors land in the workflow instead of a page event.
- Backend workflows work on Bubble's Free plan, but API calls there have limits meant for testing. In Bubble's workload units, an outbound API call costs 0.1, a server-side workflow action 0.6 and scheduling a workflow 0.1.
- Mailr mails to US addresses only and needs a two-letter state and a 5-digit or ZIP+4 code. Store the state as a two-letter code (an option set works well) so the request never fails on Arizona instead of AZ.
What it costs
Each live piece is paid from your Mailr balance, printing and postage included: a 4x6 postcard is $0.85, a 6x9 $0.89 and an 8.5x11 letter $0.95 on pay as you go, less on a plan. Test pieces are free. All prices.
Templates that fit: Welcome letter (8.5x11), First-order thank you (6x9).
Questions
Is there a Mailr plugin for Bubble?
No. The API Connector call on this page is the whole integration: the same HTTPS request any other app sends to Mailr.
How do we mail a list of users at once?
Two ways. Schedule API Workflow on a list runs send-welcome-letter for each user (set an Interval in seconds so the runs are spread out). For larger campaigns, add a second call to POST /v1/batches and build its recipients array with :format as text: up to 1,000 recipients per request, all checked before anything prints, one charge for the batch.
Will a user get two letters if the workflow runs twice?
No. The Only when check skips users who already have a mailr_letter_id, and the Idempotency-Key welcome-{unique id} makes Mailr return the first letter for 24 hours if two runs overlap.
How do we show the letter's status in the app?
Add a second call, Use as Data, GET https://api.mailr.dev/v1/flats/[id] with the id as a parameter, and show its status field. Mailr doesn't send webhooks yet, so read it when the page loads or on a recurring backend workflow.
What happens if the address is wrong?
Mailr answers 422 with the field to fix, for example to.zip, and creates nothing. Because errors are included in the response, the workflow carries on: log the error body on the record and show the user a prompt to fix their address.