Mail printed letters from ERPNext with PostGrid

This document shows how to turn any ERPNext or Frappe print format into a physical letter using the postgrid_integration app and PostGrid's Print & Mail service. Use it when invoices, statements or notices need to go out on paper, either by hand from the print view or automatically from a Notification.

The app renders the print format to a PDF, hands it to PostGrid, and records the letter on the document's timeline. PostGrid prints, stuffs and posts it. If the document only needs a signature, eSign collects one electronically with no paper involved.

Before you start

You need three things:

• A PostGrid Print & Mail account and its API keys. Keys live in the PostGrid dashboard under settings.

• Python 3.10 or newer on the bench. The app uses match statements.

• A site that PostGrid can reach over the public internet, if you want delivery status to flow back into ERPNext. See Delivery status and webhooks.

Every document you mail needs a sender address and a recipient address, both stored as Frappe Address records. Each address must have a country, because the app looks up the country code and sends it to PostGrid.

Install the app

Run these from the bench directory, as the bench user:

bench get-app avunu/postgrid_integration
bench --site <SITE_NAME> install-app postgrid_integration

The app depends on postgrid-python, pyjwt and pypdf, which bench installs with it.

Installing does two things for you. It adds a PostGrid Settings link under a "Direct Mail" card on the Integrations workspace, and on every bench migrate it adds Mailed Letter as an option to the Notification channel field and the Communication communication_type field.

Uninstalling removes the workspace link and reverts those two field options.

Configure PostGrid Settings

Open PostGrid Settings. It is a single doctype, and only users with the System Manager role can see it.

1. Paste your test key into Test API Key and, when you are ready to mail for real, your live key into Live API Key.

2. Set Mode to Test or Live. A new settings form starts on Test, the first option in the list.

3. Set the default options (see the table below).

4. Save.

On save, the app registers a webhook with PostGrid for the selected mode and generates a shared secret. The secret and webhook IDs are hidden fields. You do not copy them anywhere.

These defaults pre-fill the Mail dialog and the Notification fields. You can override them on each letter.

Test keys and live keys

The app keeps one key per mode and uses the one that matches Mode. Changing Mode is the only switch between them. Nothing else in the app differs.

Start in Test while you tune the print format and address placement. What PostGrid does with a test-mode letter, for example whether it is printed or posted, is decided by PostGrid, not by this app. Read PostGrid's own documentation for that before you assume anything.

When you switch to Live and save, the app registers a second webhook for that mode if it has none. From then on the app sends letters with your live key, so send yourself a test-mode letter first and confirm the print format and addresses look right.

Mail a document by hand

1. Open a submitted document, for example a Sales Invoice, and open its print view.

2. Pick the print format you want to send in the print view's format selector. The Mail button sends whichever format is selected.

3. Click the Mail button at the top of the print view.

4. Fill in the Mail Letter dialog and click Mail via PostGrid.

The dialog asks for:

• From Address (required). It defaults to the document's company_address, or, when ERPNext is installed, to the company's default address.

• To Address (required). It defaults to the first of customer_address, shipping_address, billing_address, supplier_address or address that the document has.

• To Contact (optional). It defaults to contact_person. The contact's first and last name go on the envelope.

• Address Placement, Envelope Type and Additional Options (double sided, color, express), pre-filled from your settings.

• With Cover Letter and Cover Letter Print Format. The cover letter is another print format for the same doctype, rendered for the same document. It goes in front of the main letter, and when Double Sided is on, the app inserts a blank page between the two.

You get an alert with a link to the Integration Request when PostGrid accepts the letter, or a red alert with a link to the failed request when it does not.

What gets recorded

Each mailing creates:

• An Integration Request for the service PostGrid, holding the request and the response, with status Queued, or Failed with the error.

• A Communication of type Mailed Letter linked to your document, with a subject of <DOCNAME> Direct Mail.

• A timeline card on the document, titled "Letter mailed to ...". It has a status pill, a link to the saved PDF when you enabled Save PDF Files, and an Open in PostGrid menu item that goes to the letter in the PostGrid dashboard.

The app also stores PostGrid's contact ID on both Address records, in a hidden postgrid_id field it adds to Address.

Automate mailings with Notifications

The app adds a Mailed Letter channel to the core Notification doctype. Create a Notification the same way you would for email, then choose Channel Mailed Letter.

1. Set Document Type and Event. In the code we read, these events fire: New, Save, Submit, Cancel, Days Before and Days After. The app does not hook the document's change event, so Value Change does not mail anything, and Method only fires for the after_insert, on_update, on_submit and on_cancel methods. We did not test the events on a live site.

2. Add a Condition to limit which documents mail.

3. Choose the Print Format to send. The app turns on attach-print for you and hides that checkbox.

4. In Direct Mail Settings, set From Address. It defaults to your company's default address when ERPNext is installed.

5. Set To Address Field, a dropdown listing every Link-to-Address field on the document type. This field is required.

6. Set the layout options: Address Placement, Envelope Type (required), Color, Double Sided, Express, and optionally With Cover Letter with a Cover Letter Print Format.

Recipients are not required for this channel. If you leave Message empty, the app fills in "See the attached document."

If the document's address field is empty when the Notification fires, no letter is sent and an Error Log entry titled "Failed to mail notification" is written. Any other failure while mailing is logged under the same title with the traceback.

Days Before and Days After events run from the daily scheduler, so the scheduler must be enabled on the site. The app skips all Notifications during imports with muted emails, patches and installs.

Known gap: To Contact Field

The Notification form has a To Contact Field, but in the code we read, mail_letter only takes the contact from the to_contact entry in the layout parameters. The Notification does not pass that entry, so the contact is not used and the envelope carries the address title as the company name only. We did not test this on a live bench. If you need a person's name on automated letters, put it in the Address title for now.

Delivery status and webhooks

PostGrid reports progress to a webhook on your site. The app creates it for you, and it listens for letter, postcard, cheque and return-envelope events. The endpoint is a guest-allowed method:

/api/method/postgrid_integration.postgrid_integration.doctype.postgrid_settings.webhooks

Each call is a signed JWT (HS256) that the app verifies with the generated secret. A call with a bad signature is rejected with an authentication error.

The app maps PostGrid statuses to the Communication's delivery status and the Integration Request status:

Only these five statuses are mapped. A status outside this list is not handled by the code we read.

The webhook URL is built from your site's configured URL. PostGrid has to be able to call that URL. If your site is not reachable from the internet, expect the status updates, saved PDFs and address updates to be missing.

The settings form has a Reset Webhooks action that registers fresh webhooks for both Test and Live. It expects both keys to be set. The code does not delete older registrations and does not save the new webhook IDs on the form, so check the PostGrid dashboard for duplicates afterwards.

When Update Addresses is on, a webhook that carries a verified address updates the matching Frappe Address (street lines, city, state, postal code, and the title when a company name is returned). It only matches addresses that already have a postgrid_id, which is set by an earlier mailing.

Limits

• Only letters work. The code for postcards and cheques is switched off in the app's MAIL_TYPES list, with a comment that it waits on those being implemented.

• The Mail button only appears for non-draft documents in the print view.

• Both addresses need a country, and the app does not verify addresses itself. A bad address fails at PostGrid and shows up in the Integration Request.

• A failed letter is not retried. Fix the cause and mail it again by hand.

• Letters are built from the PDF that Frappe renders, so what you see in the print preview is what is sent. Keep your margins compatible with the Address Placement you chose.

• The sync_contact code in the repository that would push Contacts to PostGrid is not hooked up. Its own comment says PostGrid's API does not support updating contacts.

• The app's version is 0.0.1, and it has no automated tests beyond an empty stub. Treat it as a small, useful tool, not a hardened product, and try each change on a staging site first.