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

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

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

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.
WORDPRESS

Mail from WordPress 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 190 KB · 47 text files

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