Direct mail for growth teams, with an API underneath. Read the docs →

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 happensMail 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 campaignAn 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

  1. 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.
  2. 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}.
  3. 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.
  4. 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.
  5. 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.
  6. 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.
  7. 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.

The code on this page is written against the Mailr API as it works today. Test it with your test key first; nothing prints until you use a live key.
SALESFORCE

Mail from Salesforce today

Get a free test key, send one postcard to yourself and watch it move through every status.

  • Postcards, flats and folded mailers
  • A proof before anything prints
  • Free test mode: nothing prints, nothing charges
  • A status for every piece

Download the template kit?

mailr-kit.zip · about 310 KB · 65 text files

Only HTML, JSON and Markdown files. No programs, scripts or macros, nothing that installs or runs.