View Categories

Placeholder Creation

4 min read

Table of Contents

This guide is aimed at administrators or advanced users who want to create and manage custom placeholders using the plugin’s database integration system.

Smithy Factory Emailer: Integrations & Placeholders Tutorial

What Are Integrations and Placeholders?

Placeholders are special tags (like %first_name% or %order_total%) that you can insert into your email templates. When an email is sent, these tags are replaced with real data from your WordPress or WooCommerce database.

Integrations are the rules that define how a placeholder gets its data. With the Integrations system, you can create custom placeholders for almost any field in your database—even custom fields or plugin data.

Who Should Use This Feature?

  • Administrators or trusted staff with database knowledge.
  • Anyone who wants to personalize emails with data not available in the default placeholders.

Where to Find the Integrations Panel

  1. In your WordPress admin, go to Smithy Factory Emailer.
  2. Click on Database Integrations (Admins only).

Adding a New Integration (Custom Placeholder)

1. Click “Add New Integration”

You’ll see a form to define your new placeholder.

2. Fill Out the Integration Form

  • Database Table:
    The database table where the data lives.
    Examples:
  • Table Type (set for you):
    • Direct: The value is a column in the table (e.g. users.email).
    • Meta: The value is stored as a key/value pair (e.g. usermeta.meta_key/meta_value).
  • Field:
    The column you want to pull data from (for Direct tables).
  • Meta Key:
    The key name (for Meta tables, e.g. billing_company).
  • Data Type:
    Choose the type of data (text, number, date, email, etc.). This helps with formatting.
  • Placeholder:
    The tag you’ll use in your emails, e.g. membership_level.
    Use only letters, numbers, and underscores. DO NOT INCLUDE % SIGNS these are added for you.
  • Label:
    A human-friendly name for the placeholder (shown in dropdowns).

Testing Your Placeholder

Before saving, use the Test Integrations panel:

  1. Choose if it’s a USER or ORDER placeholder
  2. Enter a sample user or order ID and the placeholder.
  3. Click “Test Placeholder.”
  4. The system will show the value that would be inserted for that user/order.

Tip: If you get a blank or error, double-check your table, field, and key names.

Example: Creating a Custom User Placeholder

Suppose you want to add a placeholder for a user’s membership level stored in usermeta as membership_level.

  • Database Table: usermeta
  • Table Type: meta
  • Meta Key: membership_level
  • Data Type: text
  • Placeholder: membership_level
  • Label: Membership Level

The system will automatically generate a query like:
SELECT meta_value FROM {wp_prefix}usermeta WHERE user_id = {user_id} AND meta_key = "membership_level"

Add the placeholder in an email and it will find the data and replace the placeholder with the users membership level.

Example: Creating a Custom Order Placeholder

Suppose you want to add a placeholder for the shipping method on an order, stored in wc_orders as shipping_method.

  • Database Table: wc_orders
  • Table Type: direct
  • Field: shipping_method
  • Data Type: text
  • Placeholder: shipping_method
  • Label: Shipping Method

The system will generate:
SELECT shipping_method FROM {wp_prefix}wc_orders WHERE id = {order_id}

Security & Best Practices

  • Sensitive Data: The system blocks access to sensitive fields (like passwords or tokens).
  • Testing: Always test new placeholders before using them in a live email.
  • Naming: Use clear, descriptive names for placeholders and labels.

Troubleshooting

  • If your placeholder returns blank, check:
    • The table and field/meta key names are correct.
    • The user/order you’re testing with actually has data for that field.
    • The context (user/order) matches your email type.

Editing or Deleting Integrations

  • You can edit or delete any custom integration from the Database Integrations list.
  • Changes take effect immediately for new emails.

Using Your Custom Placeholders

  • When composing an email, your new placeholder will appear in the “Choose Placeholder” dropdown.
  • Insert it into your email body. When the email is sent, it will be replaced with the real value for each recipient.

Summary

The Integrations/Placeholders system lets you personalise emails with many of the fields in your WordPress or WooCommerce database. Always test your placeholders, and use this feature with care.

For more help, contact your site administrator.