Direct mail API for Salesforce
Direct mail API for Salesforce: when an opportunity is closed won or a new contact is created, a record-triggered flow calls Mailr through a named credential, Mailr prints and mails a letter or postcard, and the piece id is saved back on the record.
What to mail from Salesforce
| When this happens | Mail this |
|---|---|
| Opportunity StageName changes to Closed Won (record-triggered flow, asynchronous path) | A founder welcome letter to the primary contact, mailed flat. (Welcome letter) |
| A Contact is created (record-triggered flow on Contact, asynchronous path) | The same welcome letter, sent to the new contact. (Welcome letter) |
| A Campaign Member is created on an event campaign | An event invite postcard. Copy the Apex class and set kind postcard, size 5.5x8.5 and the invite's merge fields. (Event invite) |
Set it up
- Save your return address in Mailr. In the Mailr dashboard, open Settings and save your return address. Requests can then leave out from, so the Apex action never carries an address of its own.
- Create the external credential. Setup > Named Credentials > External Credentials > New. Name it Mailr and choose the Custom authentication protocol. Add a principal with an authentication parameter named ApiKey that holds your mlr_test_ key, then a custom header named Authorization with the value {!'Bearer ' & $Credential.Mailr.ApiKey}.
- Create the named credential. Named Credentials > New: name Mailr, URL https://api.mailr.dev, external credential Mailr. Turn off Generate Authorization Header and turn on Allow Formulas in HTTP Header, so Salesforce sends the Authorization header from the external credential.
- Give users access to the credential. In a permission set, enable the Mailr principal under External Credential Principal Access and give Read access to the User External Credentials object. Assign the permission set to the users whose saves start the flow.
- Add the field and the Apex action. Add a text field Mailr Piece Id (Mailr_Piece_Id__c) to Opportunity and to Contact. Deploy MailrWelcome and MailrWelcomeTest from the tabs below; production deployments need the test class.
- Build the record-triggered flow. On Opportunity, run when a record is updated, with the entry conditions StageName equals Closed Won and Mailr_Piece_Id__c is null, only when the record is updated to meet them. Optimize for Actions and Related Records and add an asynchronous path that gets the primary contact role, calls the Apex action and saves the piece id.
- Test, then go live. Close a test opportunity whose primary contact has a US mailing address. The letter appears in your Mailr dashboard and reaches processed_for_delivery in about 8 minutes, and nothing prints. To go live, change the principal's ApiKey value to your mlr_live_ key; the flow and the code stay the same.
The credential, the flow and the Apex action
External credential (Setup > Named Credentials > External Credentials > New)
Label / Name Mailr / Mailr
Authentication Protocol Custom
Principal Named Principal, sequence 1
Authentication Parameter ApiKey = mlr_test_... (your mlr_live_ key when you go live)
Custom Header Authorization = {!'Bearer ' & $Credential.Mailr.ApiKey}
Named credential (Named Credentials > New)
Label / Name Mailr / Mailr
URL https://api.mailr.dev
External Credential Mailr
Generate Authorization Header off
Allow Formulas in HTTP Header on
Permission set "Mailr callouts"
External Credential Principal Access the Mailr principal
Object Settings User External Credentials: Read
Assigned to the users whose saves start the flow
Record-triggered flow on Opportunity
Trigger A record is updated
Entry conditions StageName Equals Closed Won AND Mailr_Piece_Id__c Is Null True
When to run Only when a record is updated to meet the condition requirements
Optimize for Actions and Related Records
Asynchronous path on (callouts can't run while the record saves)
Get Records Opportunity Contact Role: OpportunityId = {!$Record.Id}, IsPrimary = True, first record
Decision a contact role was found
Action (Apex) Mail a Mailr welcome letter
Record Id = {!$Record.Id}
Contact Id = {!Get_Primary_Contact.ContactId}
(the Apex builds the Idempotency-Key from the Record Id)
Decision Mailr piece id Is Null False
Yes: Update Records {!$Record}: Mailr_Piece_Id__c = {!Mail_Welcome.pieceId}
No: Create Records Task for {!$Record.OwnerId}, Subject = "Welcome letter not sent: " & {!Mail_Welcome.error}
For new contacts, build the same flow on Contact (A record is created) and pass {!$Record.Id} as both Record Id and Contact Id.- Flow's HTTP Callout action can reach Mailr through the same named credential, but Salesforce doesn't support request headers on that action, only headers set in the credential or added to the generated OpenAPI spec. So it can't send an Idempotency-Key per record. The Apex action can.
- Salesforce blocks callouts while a record is being saved, so the call has to run in the asynchronous path, after the save commits. A failed action isn't retried there: the Task tells someone to fix the address, and the action can be run again for that record.
- The class sends one POST /v1/batches however many records the flow hands it, so a data load that closes 200 opportunities makes one callout, well inside Apex's limit of 100 callouts per transaction. Each letter is still one piece at one price.
- A batch is all or nothing. The class checks each address first (street, two-letter state, ZIP) and returns an error for the records Mailr would reject, so one bad address doesn't stop the rest. Mailr checks format only; it doesn't verify that an address exists.
- Merge values have length caps: first_name 14 characters and company 24. The class trims them, because a longer value fails with a 422 before anything prints.
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), Event invite (5.5x8.5).
Questions
Is there a Mailr package on AppExchange?
No. Mailr has no managed package. A named credential holds the key and an Apex action calls Mailr's REST API, so there is nothing to install and the key never appears in code or in the flow.
Can I do this without Apex?
Partly. An HTTP Callout action in Flow Builder can POST to /v1/flats with the Mailr named credential. It can't send a per-record Idempotency-Key, so keep the entry condition on Mailr_Piece_Id__c to stop a second letter, or edit the action's OpenAPI spec in External Services to add the header.
Why does a single record go out as a batch?
So the action makes one callout whatever the flow hands it. Pieces come back in the order they were sent, and each one costs the same as a single letter: $0.95 for an 8.5x11 flat on pay as you go, printing and postage included.
How do I see whether the letter was delivered?
Mailr has no webhooks yet, so it can't update Salesforce on its own. GET /v1/flats/{id} with the saved piece id returns the status and every event; the Mailr dashboard shows the same.
Will a contact ever get two letters?
Not from a repeat of the same run: the Idempotency-Key returns the first letters for 24 hours. After that, the entry condition skips any record that already has a Mailr piece id.