WooCommerce direct mail: a postcard when an order is completed
WooCommerce direct mail with Mailr is one short PHP file, not a marketplace plugin: it listens for woocommerce_order_status_completed, queues a background job, and sends one HTTPS request that prints a postcard and mails it to the order's shipping address.
What to mail from WooCommerce
| When this happens | Mail this |
|---|---|
| woocommerce_order_status_completed, on a customer's first order | A thank-you postcard with a code for the next order. (First-order thank you) |
| 21 days after the order is completed (a scheduled Action Scheduler job) | A review request card for the product they bought. (Review request) |
| woocommerce_subscription_renewal_payment_failed (WooCommerce Subscriptions) | A calm billing letter. Send it after the last retry, not the first. (Failed payment) |
Set it up
- Get a test key. Create a test key in the Mailr dashboard (Developers). Test pieces are free, never print, and move through every status in about 8 minutes.
- Put the key in wp-config.php. Add define( 'MAILR_API_KEY', 'mlr_test_…' ); above the "stop editing" line. It stays out of the database, and the plugin does nothing until the constant exists.
- Add the plugin. Save the code as wp-content/mu-plugins/mailr.php (create the folder if it isn't there). Must-use plugins load on their own; there's nothing to activate. Change MAILR_FROM to your return address, and create the promo code under Marketing > Coupons.
- Complete a test order. Mark an order with a US shipping address as Completed. Action Scheduler runs the job shortly after, the order notes show the postcard id, and the piece appears in your Mailr dashboard.
- Go live. Add funds, then swap the mlr_live_ key into wp-config.php. The same code prints and mails.
The plugin: wp-content/mu-plugins/mailr.php
<?php
/**
* Plugin Name: Mailr postcards
* Description: Mails a thank-you postcard when a customer's first WooCommerce order is completed.
*/
if ( ! defined( 'MAILR_API_KEY' ) ) {
return; // define( 'MAILR_API_KEY', 'mlr_test_...' ); in wp-config.php
}
const MAILR_FROM = [ 'name' => 'Acme Outdoor', 'line1' => '1 Example Way', 'city' => 'Phoenix', 'state' => 'AZ', 'zip' => '85004' ];
// Don't call Mailr while the order saves: queue a job in Action Scheduler (it ships with WooCommerce).
add_action( 'woocommerce_order_status_completed', function ( $order_id ) {
as_enqueue_async_action( 'mailr_thank_you', [ $order_id ], 'mailr' );
} );
add_action( 'mailr_thank_you', function ( $order_id ) {
$order = wc_get_order( $order_id );
if ( ! $order || $order->get_meta( '_mailr_postcard_id' ) || 'US' !== $order->get_shipping_country() ) {
return; // gone, already mailed, or not a US address
}
// First order only: skip it if this email has another completed order.
$earlier = wc_get_orders( [
'billing_email' => $order->get_billing_email(),
'status' => [ 'wc-completed' ],
'exclude' => [ $order_id ],
'limit' => 1,
'return' => 'ids',
] );
if ( $earlier ) {
return;
}
$piece = mailr_post( '/postcards', 'wc-thank-you-' . $order_id, [
'size' => '6x9',
'template' => 'tmpl_thank_you',
'to' => mailr_shipping_address( $order ),
'from' => MAILR_FROM,
'merge' => [
'first_name' => mb_substr( $order->get_shipping_first_name(), 0, 14 ),
'promo_code' => 'THANKS15', // a coupon from Marketing > Coupons, 12 characters max
],
] );
$order->update_meta_data( '_mailr_postcard_id', $piece['id'] );
$order->add_order_note( 'Mailr thank-you postcard ' . $piece['id'] . ' (' . $piece['status'] . ').' );
$order->save();
} );
function mailr_shipping_address( WC_Order $order ) {
return [
'name' => mb_substr( $order->get_formatted_shipping_full_name(), 0, 40 ),
'line1' => $order->get_shipping_address_1(),
'line2' => $order->get_shipping_address_2(),
'city' => $order->get_shipping_city(),
'state' => $order->get_shipping_state(), // WooCommerce stores US states as two-letter codes
'zip' => $order->get_shipping_postcode(),
];
}
// Returns the created piece. Throws on anything else, so Action Scheduler marks the job failed with the reason.
function mailr_post( $path, $idempotency_key, array $body ) {
$res = wp_remote_post( 'https://api.mailr.dev/v1' . $path, [
'timeout' => 20,
'headers' => [
'Authorization' => 'Bearer ' . MAILR_API_KEY,
'Content-Type' => 'application/json',
'Idempotency-Key' => $idempotency_key,
],
'body' => wp_json_encode( $body ),
] );
if ( is_wp_error( $res ) ) {
throw new Exception( 'Mailr: ' . $res->get_error_message() );
}
$code = wp_remote_retrieve_response_code( $res );
$data = json_decode( wp_remote_retrieve_body( $res ), true );
if ( 201 !== $code ) {
throw new Exception( 'Mailr ' . $code . ': ' . ( $data['error']['message'] ?? 'unexpected response' ) );
}
return $data;
}- WooCommerce's built-in webhooks (Settings > Advanced > Webhooks) can't call Mailr on their own: they POST WooCommerce's order JSON, and the settings screen has no way to add the Authorization header. Use the action hook, or put your own endpoint in between.
- wp_remote_post gives up after 5 seconds by default; the plugin allows 20. Because the request runs inside Action Scheduler, a slow call never holds up checkout or the order screen.
- A job that throws (a network error, or a 4xx such as an address Mailr rejects) is marked failed under WooCommerce > Status > Scheduled Actions, with the reason in its log. Action Scheduler doesn't retry it by itself.
- Mailr mails to US addresses only and wants a two-letter state and a 5-digit or ZIP+4 code. WooCommerce stores US states as codes like AZ, so shipping addresses pass as they are.
- Merge values have length limits: first_name 14 characters, product_name 22, review_url 28. The code trims names; keep review links short.
- Order meta and wc_get_orders work with both HPOS (the default since WooCommerce 8.2) and the older posts storage.
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: First-order thank you (6x9), Review request (4x6), Failed payment (8.5x11).
Questions
Is there a Mailr plugin for WooCommerce?
No. Mailr has no plugin in the WordPress or WooCommerce marketplaces. The integration is the PHP file on this page calling Mailr's REST API. A coding agent can adapt it using https://mailr.dev/llms.txt or the skill in the template kit.
Will a customer get two postcards if I change the order status twice?
No. The plugin saves the postcard id on the order and checks it first, and the Idempotency-Key (wc-thank-you-{order id}) makes a repeated request within 24 hours return the first postcard instead of printing another.
Can I mail customers who ordered before I installed this?
Yes. Pull their orders with wc_get_orders and send them to POST /v1/batches, up to 1,000 recipients per request. Every address is checked before anything prints, so one bad ZIP stops the batch instead of half of it mailing.
Does it work with WooCommerce Subscriptions?
The same pattern works with its hooks. woocommerce_subscription_renewal_payment_failed passes the subscription; send the tmpl_payment_failed letter with first_name, plan and a short update_url once your retries have run out.