WordPress direct mail: welcome letters from PHP hooks
WordPress direct mail takes one must-use plugin: it hooks user_register, schedules a WP-Cron event, and three days later sends the new member's address to Mailr with wp_remote_post. Mailr prints and mails a welcome letter, and the plugin saves its id in user meta.
What to mail from WordPress
| When this happens | Mail this |
|---|---|
| user_register (a new member signs up) | A founder welcome letter three days later, scheduled with WP-Cron. (Welcome letter) |
| gform_after_submission (a Gravity Forms catalog or sample request) | A postcard in your own design to the address on the form. |
| set_user_role (a member moves to a paid role) | A thank-you postcard in your own design. |
Set it up
- Add your key to wp-config.php. Define MAILR_API_KEY above the line that says to stop editing. It stays out of the database, the admin screens and your theme.
- Make sure you have an address. WordPress itself doesn't collect mailing addresses. The plugin reads them from user meta (mailing_line1, mailing_city and so on); rename those keys to whatever your registration form saves. Mailr needs a two-letter state and a 5-digit ZIP.
- Drop in the plugin. Save the file as wp-content/mu-plugins/mailr.php. Must-use plugins run without activation and can't be switched off from the admin. WordPress only loads PHP files directly in that folder, not in subfolders.
- Test, then go live. With a test key, register a user with your own address. To see it sooner, change 3 * DAY_IN_SECONDS to 60 and load any page after a minute. The letter appears in your Mailr dashboard; swap in the live key when it looks right.
The plugin
<?php
/**
* Plugin Name: Mailr welcome letters
* Description: Mails a welcome letter through the Mailr API three days after a user registers.
*/
function mailr_post( $path, array $body, $idempotency_key ) {
if ( ! defined( 'MAILR_API_KEY' ) ) {
return new WP_Error( 'mailr_no_key', 'Define MAILR_API_KEY in wp-config.php.' );
}
$response = wp_remote_post( 'https://api.mailr.dev/v1' . $path, array(
'timeout' => 20,
'headers' => array(
'Authorization' => 'Bearer ' . MAILR_API_KEY,
'Content-Type' => 'application/json',
'Idempotency-Key' => $idempotency_key,
),
'body' => wp_json_encode( $body ),
) );
if ( is_wp_error( $response ) ) {
return $response;
}
$code = wp_remote_retrieve_response_code( $response );
$data = json_decode( wp_remote_retrieve_body( $response ), true );
if ( $code < 200 || $code >= 300 ) {
return new WP_Error( 'mailr_' . $code, isset( $data['error']['message'] ) ? $data['error']['message'] : 'Mailr request failed' );
}
return $data;
}
add_action( 'user_register', function ( $user_id ) {
wp_schedule_single_event( time() + 3 * DAY_IN_SECONDS, 'mailr_send_welcome', array( $user_id ) );
} );
add_action( 'mailr_send_welcome', function ( $user_id ) {
if ( get_user_meta( $user_id, 'mailr_welcome_id', true ) ) {
return; // already mailed
}
$user = get_userdata( $user_id );
$meta = function ( $key ) use ( $user_id ) {
return get_user_meta( $user_id, $key, true );
};
if ( ! $user || ! $meta( 'mailing_line1' ) ) {
return; // no address on file
}
$name = trim( $user->first_name . ' ' . $user->last_name );
$letter = mailr_post( '/flats', array(
'size' => '8.5x11',
'template' => 'tmpl_welcome',
'to' => array(
'name' => $name ? $name : $user->display_name,
'line1' => $meta( 'mailing_line1' ),
'line2' => $meta( 'mailing_line2' ),
'city' => $meta( 'mailing_city' ),
'state' => $meta( 'mailing_state' ),
'zip' => $meta( 'mailing_zip' ),
),
'from' => array( 'name' => 'Northwind', 'line1' => '1 Example Way', 'city' => 'Phoenix', 'state' => 'AZ', 'zip' => '85004' ),
'merge' => array(
'first_name' => $user->first_name ? $user->first_name : $user->display_name,
'company' => $meta( 'company' ) ? $meta( 'company' ) : 'your team',
'founder_name' => 'Sam',
),
), 'welcome-' . $user_id );
if ( is_wp_error( $letter ) ) {
error_log( 'Mailr: ' . $letter->get_error_message() );
return;
}
update_user_meta( $user_id, 'mailr_welcome_id', $letter['id'] );
} );- user_register fires before all user meta is saved, so the plugin reads the address later from the scheduled event, not inside the hook.
- WP-Cron only runs when someone loads a page, so a quiet site can send late. Set DISABLE_WP_CRON to true in wp-config.php and call wp-cron.php from a real cron job if timing matters.
- The plugin checks for a saved mailr_welcome_id before sending, and the Idempotency-Key welcome-<user id> makes a retried request return the first letter instead of mailing a second one.
- Merge values have caps: first_name 14 characters, company 24, founder_name 16. A longer value fails with a 422 and the error goes to your PHP error log, so trim long names first.
- Gravity Forms runs gform_after_submission for entries marked as spam too, so skip spam entries before mailing anything from a form.
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).
Questions
Is there a Mailr WordPress plugin?
Not yet. The file above is the whole integration: one function that calls the API with wp_remote_post and two hooks.
Why a must-use plugin and not functions.php?
Code in a theme's functions.php stops running when you switch themes. A must-use plugin keeps mailing whatever theme is active, and nobody can deactivate it from the admin by accident.
Where do I see what was sent?
Every piece is in your Mailr dashboard with its status. The plugin also saves the letter's id in user meta as mailr_welcome_id, so you can look it up with GET /v1/flats/{id}. Mailr has no webhooks yet.