ProMailer manual

ProMailer handles all key aspects of managing email newsletters, subscribers and distributions from your ProcessWire installation, in a manner that gives you full control.

ProMailer is simple to get up and running, you can be sending emails to subscribers in a manner of minutes. ProMailer enables you to create subscriber lists, subscription forms, and messages to send with very little work. However, if you want to go more in depth and customize every aspect of the process, you can do that too. This manual has you covered either way. If you are just getting started, I recommend at least reading the “Setting up and using ProMailer” section when using ProMailer for the first time.

Installing ProMailer

We recommend ProcessWire 3.0.123 or newer for ProMailer. It may also work in earlier versions, but is not guaranteed.

  1. On your web server (or dev environment) copy all the files for this module into /site/modules/ProMailer/.
  2. In your admin, go to Modules > Refresh.
  3. Click Install for the ProMailer module.
  4. After the module installs, enter your product key on the module configuration screen.

Setting up and using ProMailer

This section will get you up and running with ProMailer, introducing everything you need to know to setup and maintain subscriber lists and send emails to them. While ProMailer is largely self explanatory, we recommend following the instructions in the order presented here.

Create a new subscriber list

1. In your admin, navigate to: Setup > ProMailer > Subscriber Lists > Add New:

  • We are creating your master/primary subscribers list, not a testing list. We will create a second list for testing purposes in step 3. But we want list ID=1 (the first one created) to be your primary list.

  • For the “List title” enter a name like “Newsletter subscribers” or similar that applies to your need.

  • Please select the “New subscribers list managed by ProMailer” list type rather than a “Users/pages” list type. We will cover the Users/pages list type later.

  • Save your new list.

2. Optionally add one or more email addresses to this list:

  • If you already have a list of email addresses to add, you can start adding/importing subscribers to the list now, or you can return to this part later when/if needed.

  • Any subscribers you add manually to the list are considered already confirmed/opt-in subscribers.

3. Add a second subscribers list for testing purposes.

You will use this list to test sending messages to yourself before sending to your master/primary subscribers list.

  • Create this list the same way you did the previous by navigating to Setup > ProMailer > Subscriber Lists > Add New. Give the list a title of “Test list” or something similar.

  • Make sure the list type is the default setting, “New subscribers list managed by ProMailer”.

  • Add at least one of your own email addresses to this list.

  • In the “List settings” fieldset, locate the “List status” field and select “Closed (subscribe disabled)”, since this is your testing list and you don’t want others to be able to subscribe to it.

  • Save your test list.

Now let’s setup a subscription form so that users can subscribe to your master/primary list…

Setup the subscription form

When you installed ProMailer, it created a /promailer/ page in your site with the title “Subscribe”. This page handles the subscribe and unsubscribe functions of your lists. Feel free to move and/or rename this page to whatever and wherever you want. However, it should always use the template “promailer-subscribe” that was automatically installed with ProMailer. You may add fields to the template later if you’d like, but do not rename the template.

1. Open the promailer-subscribe template file to edit:

  • Using an HTML/code or text editor, open and edit the template file for your /promailer/ page, which is located here: /site/templates/promailer-subscribe.php

  • If for some reason this template file isn’t there, copy /site/modules/ProMailer/promailer-subscribe.php into /site/templates/ yourself, and then edit it.

2. Modify the bottom of the template file consistent with your site’s output strategy:

  • ProcessWire supports several different ways to output markup and ProMailer doesn’t know what output strategy you are using in your site. Chances are that in order for your Subscribe page to be usable, you will need to modify the code at the bottom of it in order to ensure its output goes into the right place.

  • Locate the section titled “MAIN OUTPUT” at the bottom of template file and update it as needed for your site’s output.

3. Modify the Subscribe form (and Unsubscribe form) markup:

  • This step is optional at this stage, so you can return to it later after you’ve got everything else working, if you’d prefer. The default markup will work just fine, but it may not be pretty (depending on your site’s CSS styles).

  • In this template file you’ll see it defining two variables containing form markup: $subscribeForm and $unsubscribeForm. The default markup is very basic in order to ensure that it is simple for you to modify. You may want to update the form markup to better suit the markup and CSS style of your website.

  • The forms contain several {placeholder} tags that are replaced with actual values at runtime. You’ll want to keep these placeholder tags in place.

4. Test out the subscribe form:

Once you've finished making edits to this file, test out your subscription form by viewing the /promailer/ page on your website (or whatever you renamed it to). Make sure that all of the following work properly:

  • You can subscribe to your master/primary list.
  • You receive a confirmation email.
  • You can click the link in the email to confirm your subscription.
  • Your website outputs a thank you confirmation message.
  • In the ProMailer admin: you can see your email in your list with “opt-in” checked.

If for some reason you do not receive a confirmation email: there’s a good chance your web server is not configured for sending email. Sometimes web servers aren’t ideal for sending email, and there are significant benefits to using an external mail sending service (like Mailgun, SendGrid, Amazon SES, etc). These services are very low-cost (or often free) and simple to setup. For more details, see the section further down on using external email providers with ProMailer.

Edit the “Test email” page

Below your /promailer/ page (or whatever you renamed it to) will be an example of an email page that you can use for testing purposes. The default path of this page at installation time is /promailer/email-example/. This page is simply an example of an email template that you might send to a list. Whether you end up using it or not, it’s a good place to start testing ProMailer.

1. In the ProcessWire admin, edit your /promailer/email-example/ page:

  • Type or paste some example content into the page’s “body” field.
  • Save and then View the page. This is a preview of your email.

If you do not see a “View” link for this page, then it means the template file is missing. If that’s the case, copy the file /site/modules/ProMailer/promailer-email.php to /site/templates/promailer-email.php, and then you should be able to view the page.

2. Try out a placeholder (optional):

  • Edit the email example page again and type/paste in the text {email} somewhere in the “body” field. Save.

  • Note that when you view the page here the placeholder will remain unpopulated. But when sent as an email, the placeholder would be populated with the user’s email address—we’ll see it in action soon. For now we’re just demonstrating what a placeholder is.

3. Edit the promailer-email.php template file (optional but recommended):

  • Whether now or later, you might also want to open and edit the template file that this page uses, just to see how it works. The file is /site/templates/promailer-email.php. Use your favorite markup/code/text editor.

  • This file has instructions and tips on how to prepare an email template, as well as information on email frameworks that you might use for this or other email templates.

Note that there is absolutely no requirement that you use this page or template for your ProMailer emails. This page and template are installed by ProMailer just to introduce things to you. You can of course continue to use this template for future emails if you’d like (modifying it as you see fit), or you can create your own email templates. When/if you create your own email templates, feel free to delete the email-example page and/or template if you no longer need it.

Create and send a test message

A message in ProMailer is where all the action happens. It is where you select the subscribers list to send to, and the content (or page) to send. Let’s create a new message to test things out…

1. In your ProMailer admin create a new test message:

  • Navigate to Setup > ProMailer > Messages > Add New.
  • Title the new message as “Test message” or something similar, and Submit.

2. Populate the message settings:

On the next screen after creating your message, it’ll give you several more fields for the message settings. Populate all required fields, as well as the following (many of which may already be pre-selected):

  • For “Body source” select “Page that renders the body”.
  • For “Select page that renders body” select the “Email example” page (/promailer/email-example/).
  • For “Body content type” select “Separate HTML and text versions”.
  • For “Send to subscriber list” select your “Test list” that you created earlier.
  • For “Throttle seconds” I recommend between 1 and 3 seconds for now (feel free to adjust later).
  • For “Send quantity” I recommend entering 1 for now (feel free to adjust later).
  • For “Send type” I recommend selecting “Live” at this stage, though it’s not required.

3. “Submit” to save your message and then test sending it:

  • Click the “Start sending” button to send the test email to your test subscribers list.
  • Wait until it finishes sending, then proceed to step 4.

4. Make sure that you receive the test email:

  • If for some reason you do not receive the test email, wait a few minutes and check your spam folder as well.

  • If you do not receive the email, or if it goes to your spam folder, read further down for the section on “Using an external email sending service”.

If you are testing things out from your localhost/development computer, you may not be able to send email from that environment unless using an external email sending service. Our home/work computers (as opposed to servers) usually aren’t setup for (or allowed to) send email in this manner, unless connected to an external email service.

5. Test the “Unsubscribe” function:

  • Click the “unsubscribe” link in the test email you received to make sure that the unsubscribe function is working.

  • After clicking the link, it will open your /promailer/ page on your web site. It will ask you to confirm that you want to unsubscribe. Confirm it.

  • After confirming, verify in your ProMailer “test list” (in the admin) that your email address no longer appears in the list.

  • Go ahead and add your email address back into the test list.

Finishing up and next steps

If everything has worked so far you should be in good shape to start using ProMailer in production. I recommend taking these next steps:

  • Modify the promailer-email.php template file to match your branding or create your own new template for the purpose.

  • Modify the promailer-subscribe.php template file as needed to look good in your website. You can also adjust the text labels and success/error messages as you see fit.

  • If in a non-English multi-language environment, go to Setup > Languages > [language] in your admin and click the “Add files to translate” button for the “Site translation files”. Add the /site/templates/promailer-subscribe.php file and then translate all of the text as needed.

  • Any questions? Feel free to post in the ProMailer support board at https://processwire.com/talk/.

Using an external email sending service

It’s common to use an external email sending service (or external SMTP service) to handle the actual email sending. This is because web servers often are not configured ideally for sending email, or place substantial limitations on how much email you can send. Either now or when you outgrow your web server, consider using a dedicated email service such as Mailgun, Mailjet, SendGrid, Amazon SES, or any other specialized email service that supports bulk email (not just transactional email).

To use these services, you will want to install one of the WireMail modules available for ProcessWire and then configure it for your email service. Once installed, it will become an option for email delivery in ProMailer.

Not sure where to start?

One to consider is Mailgun as there is a dedicated ProcessWire WireMail module available for it (WireMailMailgun). They also provide good instruction on any DNS changes helpful for maximizing the delivery of your emails. It supports bulk mail, has built-in monitoring and analytics, and good support for webhooks (which ProMailer also supports).

Ultimately it doesn’t matter what email service or WireMail module that you use, but I can only report on those that I’ve personally used. I’ve used Mandrill, SendGrid, AWS SES and Mailgun for our transactional and bulk email at processwire.com and all have worked well.

WireMail modules you might find useful with ProMailer include:

Of those listed above, I have personally used PHPMailer, Mailgun, WireMailSMTP and SwiftMailer, and all worked well.

Using a pre-subscription form

ProMailer comes with a ready-to-use subscription page and form. But often on websites, you want a subscription form to appear on every page in the website, perhaps in the footer or the sidebar. Given that, the promailer-subscribe.php file is designed so that you can include it from other template files, and it should render the form wherever you include it, while disabling the functions that are not needed in this context. You can include it from any other template file like this:

<?php include('./promailer-subscribe.php'); ?>

At processwire.com, we opted not to do it that way, in part because the feature wasn’t available at the time, though also because our pre-subscription form is is just an email input and nothing more. Our pre-subscription form appears in the footer of every page on the website. It’s called a pre-subscription form because it is just an “email address” field that a visitor populates before being taken to the actual subscription form. This makes the real subscription form essentially a confirmation form, just verifying that they really want to subscribe and/or asking them for any additional fields needed to subscribe.

If you want to implement your own pre-subscription form, you can use your own markup. Have it submit (GET not POST) to the /promailer/ page (or whatever you renamed it to), with a field named “email” containing the email address. The promailer-subcribe.php template file is designed for this usage and will pre-populate the submitted email address to the subscription form where the user can complete their subscription. Here’s an example of such a pre-subscription form that you might use (adjusting the markup as you see fit):

<form method='get' action='/promailer/'>
  <label for='email'>Email address</label>
  <input type='email' id='email' name='email'>
  <button type='submit'>Subscribe</button>
</form>

Note that you’ll want to update the form’s “action” attribute to point to your subscribe page that uses the promailer-subscribe template, wherever it happens to be located (the default location is /promailer/).

Maintaining custom fields for subscribers

By default, ProMailer maintains just an email address for subscribers to your list(s). But perhaps you would like to maintain additional fields such as first and last name, company, age, or others. ProMailer supports this. To demonstrate, we will maintain first_name, last_name and age fields in our subscribers list. Here’s how to set it up:

1. In the ProMailer admin, edit the subscriber list where you want to have custom fields:

  • Click the “Tools” fieldset and then click the “Define custom fields” field to open it.

2. In the “Define custom fields” enter the following:

*first_name:text
last_name:text
age:int

  • This tells ProMailer that we want have first_name and last_name fields that are sanitized as plain “text”, and we want to have an age field that is sanitized as an integer. The words “text” and “int” refer to methods in ProcessWire’s $sanitizer API variable. You can use any sanitizer name that is appropriate for your field.

  • The asterisk * that we prepended to “*first_name” indicates that the field is required on our subscribe form. Use asterisks after the sanitizer name for any other custom fields that you want to be required.

Advanced feature: In ProcessWire 3.0.125 and newer (only), you can also specify multiple sanitizer names (if needed) by separating each with an underscore. In these core versions, many sanitizers also support a length argument appended to the sanitizer name, enabling you to combine sanitizers and specify bounds like this “age:int_min10_max110”, which says to define an age field that is an integer with allowable values between 10 and 110. For a simple subscribers list, this may be overkill, but I mention it just so you know the option is there if it arises.

Advanced feature: If for some reason you want to define a field that can never be input from the subscription form, append an exclamation point (rather than the optional asterisk) to the sanitizer name, i.e. “text!”.

3. Save your custom fields:

  • After entering the above custom field definitions, click Submit to save your custom fields and make them part of the subscriber list.

4. Verify custom fields are working:

  • After adding your custom field definitions, you’ll notice that any current subscribers in the list now show empty first_name, last_name, and age fields, presented as columns in the subscribers table.

  • You can populate these fields directly in your subscribers list, but chances are you’ll instead want to collect this information from your subscription form, which we’ll cover below.

  • When importing new subscribers from a CSV file, you can also import custom fields as well, so long as the names in the CSV header match the names of your custom fields.

5. Add the custom fields to your subscribe form:

To add your custom fields to your subscribe form, you’ll need to edit your /site/templates/promailer-subscribe.php template file and add the fields to your subscribe form markup. Use the same field names that you used in your custom field definitions, and ProMailer already knows to expect them in the input. For your required fields, you should also add HTML5 required attributes to the <input> tag. Below you can see the first three <p> elements that we added to the form for first_name, last_name and age:

<form id='promailer-form' action='{url}#promailer-form' method='post'>
  <p>
    <label for='first_name'>First name</label>
    <input required type='text' name='first_name' id='first_name'>
  </p>
  <p>
    <label for='last_name'>Last name</label>
    <input type='text' name='last_name' id='last_name'>
  </p>
  <p>
    <label for='age'>How many years old are you?</label>
    <input type='number' name='age' id='age' min='8' max='120'>
  </p>
  <p>
    <label for='{email_name}'>{email_label}</label>
    <input required type='email' id='{email_name}' name='{email_name}' value=''>
  </p>
  {honeypot}
  <button type='submit' name='{submit_name}' value='1'>{submit_label}</button>
  {extras}
</form>

6. Test out your subscribe form:

  • With your subscribe form markup now in place, test it out on the front-end of your website, ensuring that your new custom fields are correctly populated into the subscriber list.

  • If or when you want to use these custom fields in your emails, you can use placeholders such as {first_name}, {last_name}, {age}, etc. You can use these placeholders directly in your email template file(s), or you can use them in the body copy of page that represents your message.

Custom fields reference

Custom fields for a list are defined in the “List settings” in the “Define custom fields” textarea input. One custom field is defined per line in this field using this format:

name:type

The name can be any combination of letters, numbers or underscores that would also be a valid PHP variable name. The type can be the name of a $sanitizer method that would enforce its type via sanitization, such as “text”, “int”, etc. For example:

first_name:text

To make a field required, prepend an asterisk to the name, i.e.

*first_name:text

Above we’ve chosen “text” as the type, and this is the most likely type to use with these definitions. But there are many other types you can potentially choose. These types affect not only how the value is sanitized, but can also dictate what type of input is used for the value. Below are a list of sanitizer names (types) that I think may be useful in this custom fields definition:

Strings

  • text - single line of text up to 255 characters and no markup
  • textarea - multiple lines of text with no markup
  • alpha - Letters a-z A-Z only
  • alphanumeric - Letters or numbers a-z A-Z 0-9
  • digits - Digit string useful for things like ZIP codes
  • email - Email address
  • url - URL or path
  • httpUrl - URL with domain and HTTP/HTTPS scheme required (PW 3.0.129+)

Numbers

  • int - Positive integer
  • intUnsigned - Positive integer (alias of int)
  • intSigned - Positive or negative integer
  • float - Floating point number

Selection

  • option - Single selectable option presented in a <select>
  • options - Multiple selectable options presented as checkboxes
  • bool - Single checkbox that contains boolean true or false
  • bit - Single checkbox that contains 1 or 0 (3.0.125+)

Using single and multiple choice types (option or options)

When you choose “option” as the type, ProMailer interprets this to mean a single selectable option in a <select> input. And when you choose “options” (plural) as the type, ProMailer interprets this to mean multiple-choice checkboxes. Since both of these types require a list of options to select from, you can define those options like this:

gender:option [ Male | Female | Other ]
interests:options [ Markup and CSS | Javascript | Server-side PHP ]

Basically, you provide the options between “[“ and “]” brackets and separate them by pipes “|”. The spaces between the option values, bracket and pipes are ignored — they are just for readability here and are not required.

If you want to maintain separate option values and labels, then you can specify them like this:

gender:option [ m=Male | f=Female | o=Other ]
interests:options [ HTML=Markup and CSS | JS=Javascript | PHP=Server-side PHP ]

Note: you can optionally place quotes around the option labels, but it is not required.

Specifying other attributes

You can also define other attributes such as the default selected “value”, the “placeholder” text, the “label” that appears with the field, and any other attributes you want present on the <input> or <select> elements. To do this, specify them in HTML attribute format within parenthesis at the end of the custom field definition:

first_name:text (label="First name" placeholder="i.e. Bob")
gender:option [ m=Male | f=Female | o=Other ] (value=o)

Like in HTML, quotes around the attribute values are only required if the attributes have whitespace or some other punctuation character that might confuse the parser.

Removing or renaming a custom field

To remove a custom field, simply delete the entire line from the “Define custom fields” input. Note that any subscribers that contain entries for deleted custom fields will continue to retain that data until the subscriber is next saved, though the data won’t be used or visible anywhere. The cleanup process happens whenever a subscriber is saved.

You can rename a custom field by changing the name in the definition line, but note that any subscriber data already in the database will still be keyed to the old name, so if you need to rename any custom fields, you should preferably do so before collecting that data from subscribers.

Custom fields, placeholders and conditionals

Any custom fields can be referenced in your email template or body by using the placeholder, which is the field name surrounded by curly brackets. For instance, the placeholder for a custom field named first_name would be {first_name}.

Your use of placeholders may sometimes be conditional in that you want to display the value of a custom field along with some related text, but only if the custom field happens to be populated. ProMailer supports this with conditional placeholders, which are if, else and endif statements surrounded in curly brackets. These are best demonstrated by example.

In the ProcessWire Weekly newsletter that we send out every week, the first line in the email reads "Hi Bob, Welcome to ProcessWire Weekly", but only if the first_name field is populated. If first_name is not populated, then it just starts with "Welcome to ProcessWire Weekly". The way we accomplish that is by using this conditional placeholder in our email body:

{if:first_name} Hi {first_name}, {endif} Welcome to ProcessWire Weekly

While this could go in our email template file, we place it directly in our email body by editing the page for our ProcessWire Weekly email. This is just a simple example. Lets look at some more examples below that demonstrate the scope of conditional placeholders. Note that it does not matter if you put conditionals on a single line or multiple lines, but since they are easier to read on multiple lines, that's what we're doing with our examples below:

// example with else condition
{if:first_name}
  Hello {first_name},
{else}
  Hello friend,
{endif}

// when nesting statements, append the {endif} with the field name,
// for example: i.e {endif:last_name}
// may occasionally be necessary with {else} as well
{if:first_name}
  {if:last_name}
    Hello {first_name} {last_name},
  {else}
    Hello {first_name},
  {endif:last_name}
{else}
  Hello friend,
{endif:first_name}

// example of ifnot condition (opposite of if condition)
{ifnot:first_name}
  Hello friend,
{else}
  Hello {first_name},
{endif}

About the “Users/pages” list type

In addition to ProMailer-managed subscribers lists, ProMailer also supports lists that match a selection of ProcessWire users or other pages. To create a list of this type, you would select “Users (or pages) matching your query/selection” as the “Type of list to add” when creating a new list.

This list type is primarily useful for emailing other users in your system. For instance, maybe you want to let all users know of a maintenance outage or newly added feature, and this is a good way to do that.

Another scenario is if you are using ProcessWire pages to represent items that are each associated with an email address. For instance, in the ProcessWire modules directory, we use pages to represent each 3rd party Module that users can view on the front-end of the site. Each of these modules is associated with an email address. So if we wanted to email all 3rd party module developers in that site, we could easily do so by creating a list that matches those pages. Or if we wanted to send an email to all module developers that have a module in the “Language packs” category, we could easily define a list for that.

A list of this type is considered an automatic opt-in list since you are already controlling who is in the list from your query/selection. There is no subscribe form for this type of list since it is based upon your predefined selection of pages. However, users can opt-out of these types of lists by checking a box in their ProcessWire profile settings. This list type is also considered a dynamic list since it matches users/pages matching a query at the time the message is sent, rather than a predefined static list of emails.

If you are creating a list that matches pages that are not using the “user” template, and you want to have an unsubscribe option, add the field “promailer_unsubscribe” to the template(s) used by pages in your list. (This is a field that ProMailer created at installation time).

Sending email: live vs. background

When it comes to sending a message in ProMailer, you have two options: “Live” and “Background”. Both accomplish the same thing, but how they accomplish it is very different.

Live sending

Live sending requires that you keep your browser window open to the ProMailer sending page. It will update every second or so (however configured) to send the next message(s) in the queue. If you navigate away from the sending page, the email will stop sending. So long as you stay on the page, you can view the current sending status, who it’s currently sending to, what’s being sent, how many messages have been sent, and how long it’s been sending.

Background sending

Background sending on the other hand happens whether you are there with a browser window open to it or not. Background sending is triggered by any web requests to the server, and happens after delivery of each request (within the configured delay and quantity times). Essentially, users navigating your website are triggering the sending queue. You can also keep a window open to the background sending status page, monitoring the progress. This is helpful if your website is fairly low traffic (or delivered from a cache) because your own browser will continue to trigger regular requests to ensure all email is delivered in a timely fashion.

Which sending method is best?

It depends. I suggest trying out both to see what works best for your case. Most of the time I use the “live” sending method, in part because that’s what I’ve used in one form or another for the last 15 years, so it’s driven a lot more miles than the background sending method for me. The background sending method is new to ProMailer, so I didn’t have the option prior to this.

The “live” sending method is also a little more verbose than the background sending method, providing more information about the current status. A minor drawback with the “live” sending method is that I’ve got to keep my computer on and open to the ProMailer window until the send finishes. If something interrupts the connection, that’s no problem—it doesn’t lose its spot. So we can always return to it and continue where we left off. But every once in awhile my browser window will crash and there will be a Chrome error message waiting for me. I believe this is due to a browser bug or memory issue (and may be isolated to my computer), but it’s something to be aware of just in case — check in on your sending status every once in awhile to make sure it doesn’t need a reset. The background sending method would not be prone to this particular issue, so it may prove the more reliable solution long term.

Working with email page template files

These instructions also appear in the promailer-email.php template file.

Placeholders

There are several {placeholders} that you can use which will be automatically populated in sent emails. Note that these are not populated when viewing the page in ProcessWire, they are only populated when messages are sent by ProMailer:

  • {email} Email address of recipient (TO email)
  • {from_email} Email address of the sender (FROM email)
  • {from_name} Name of the sender
  • {subject} Subject of the message
  • {title} Title of the message (as identified in ProMailer admin)
  • {unsubscribe_url} URL to unsubscribe user from this list
  • {subscribe_url} URL to subscribe to this list
  • PLUS any custom fields that you defined (see the “Custom fields reference” section above)

URL variables

Each rendered message will also receive several GET variables in the URL (query string). The only one that you may initially want is the $type variable, but the others are also present should you ever want them:

$input->get('type'); // Message type, either "html" or "text" (string)
$input->get('subscriber_id'); // ID of subscriber (int)
$input->get('message_id'); // ID of message (int)
$input->get('list_id'); // ID of subscriber list (int)

Note: if you are viewing a page using an email template on its own (without ProMailer) then none of these GET variables will be present, unless you populate them yourself.

Email development tips

Use absolute (not relative) URLs for links to any assets such as other URLs or images. For instance, your URLs should begin with "https://domain.com/" and not "/". However, there are places where you may not have control over this (like in CKEditor body copy), so do not worry, ProMailer will convert any relative URLs to absolute for you.

Email clients can sometimes be pretty primitive with their HTML rendering ability, especially Microsoft Outlook. But even Gmail has its quirks. If you don’t have the time or patience to test your email in various email clients, one good option is to use an existing HTML/CSS email framework. Here are a few examples:

About the ProMailer “Subscribe” page template file

These instructions also appear in the promailer-subscribe.php template file.

This template file should be named: /site/templates/promailer-subscribe.php and should be used by 1 page in your site (which ProMailer sets up for you). Feel free to modify anything in this file as you see fit.

The purpose of this template file is to manage subscriptions and un-subscriptions for ProMailer. It also is also the endpoint for webhook submissions from your mail delivery service (if used).

If you are not using user initiated subscribe/unsubscribe features then you do not need this template file or the page using it. If you do want these features (and most likely you do) then read on…

1. This template file just outputs a form to subscribe or unsubscribe and needs to be updated to work with your output strategy. Depending on your output strategy, you should modify this file as follows:

  • If you are using direct output, you'll want to add include() statements for your header/footer files where output is rendered at the bottom of this file.

  • If you are using delayed output, you'll want to modify the last line in this file containing the $out variable to populate whatever variable you need, i.e. $bodycopy = $out; or similar.

  • If you are using Markup Regions, you'll want to modify the last line in this file to be something like echo "<div id='content'>$out</div>"; where "content" would be the id of the element you want to populate.

  • If you aren't sure what you are using, then leave things as they are for now and try to view the page using this template file to see whether or not it works. Make adjustments as needed, or post in the ProMailer support board and we can help you figure it out.

2. This file contains several options and markup that you can modify as needed.

  • For instance, you may want to update the form markup, and the error/success message markup.

  • Or you may want to modify the labels used for fields and/or error/success messages.

  • Or maybe you want to modify the contents or markup of the confirmation email that a user receives after subscribing to your list.

  • When it comes to markup, numerous placeholders like {this} are used, and those are tags that ProMailer replaces with the appropriate text during rendering.

3. If you'd like, you can make your own subscribe form completely independent of this file:

  • In that case, simply use the page (represented by promailer-subscribe.php template file) as the form processor.

  • If you do this, then specify false for the useCSRF option on the subscribe form, make sure you use the same <form> “action” attribute and <input> “name” attributes. For instance, the email field should be named "subscribe_email" and the submit field should be named "subscribe_submit".

4. If you want to use webhooks to manage things like bounces:

  • Copy the file /site/modules/ProMailer/promailer-webhooks.inc to your /site/templates/ directory.

  • The promailer-subscribe.php template file will detect and include it when present.

  • Read the documentation in the promailer-webhooks.inc file for more information about how to use it.

5. If you want to render a subscribe form from another page template file:

You may include the promailer-subscribe.php template file from other template files and it will simply output the subscribe form at the location where you include it:

include('./promailer-subscribe.php');

Modifying the “Subscribe” form

1. Modify the form markup for the subscribe form as needed.

You may use the following placeholders in the markup, which are automatically replaced with the necessary values by ProMailer when the form is rendered:

  • {list} - Title of the list being subscribed to
  • {list_id} - ID of the list being subscribed to (you probably do not need this).
  • {url} - URL the form should submit to, aka action attribute (required).
  • {email_name} - Name for the email input field (required).
  • {email_placeholder} - Placeholder text for email input (optional).
  • {submit_name} - Name attribute for the submit button (required).
  • {submit_label} - Text label for submit button (optional).
  • {honeypot} - This is replaced with an invisible spam-prevention honeypot input (optional).
  • {extras} - Extra markup & hidden inputs that ProMailer needs to place in the form (required).

2. If you have any custom fields you also want to use, please do the following:

  • Add new inputs for them in the form markup, using your own markup. You do NOT have to use placeholders for attributes or labels like the default fields, just write the markup how you usually would.

  • For the name attributes, use the same names you defined for the “Define custom fields” section of your List in the ProMailer admin.

  • For any required fields, add an HTML5 required="required" attributes to the <input> elements.

3. Modify the “Subscribe options” $subscribeOptions array that appears below the form markup in the template file.

  • There are many settings, feel free to modify as you see fit, though for most the defaults are just fine.

  • Please at least populate the emailFrom option, which will be used as the “from” address on the double opt-in confirmation email that the user receives to confirm their subscription.

4. If using multi-language support:

  • Translate this file (/site/templates/promailer-subscribe.php) in Setup > Languages > each language, as needed.

Modifying the “Unsubscribe” form

1. Modify the form markup for the unsubscribe form in the template file as needed:

You may use the following placeholders in the markup, which are automatically replaced with the necessary values by ProMailer when the form is rendered:

  • {list} - Title of the list being unsubscribed from.
  • {list_id} - ID of the list being unsubscribed from (you probably do not need this).
  • {url} - URL the form should submit to, aka action attribute (required).
  • {email_name} - Name for the email input field (required).
  • {email_value} - Pre-populated value for the email field (required).
  • {submit_name} - Name attribute for the submit button (required).
  • {submit_label} - Text label for submit button (optional).
  • {extras} - Extra markup & hidden inputs that ProMailer needs to place in the form (required).

2. Modify the “Unsubscribe options” $unsubscribeOptions array that appears below the form markup.

  • There are many settings, feel free to modify as you see fit, though for most the defaults are just fine.

Using webhooks in ProMailer

Many external email providers (like Mailgun) provide numerous webhooks that you can capture and act upon within ProMailer. The most common use case would be to capture a bounce to an email address. This is worthwhile in order to maintain a clean list. However, webhooks can also be used for capturing spam-complaints, views, clicks and more.

In order to use webhooks, you would need to use an external email service provider and WireMail module, as a local SMTP sending service on a web server is not going to have that option. Because the implementation of webhooks varies depending on your external email service provider, ProMailer includes just an example implementation for Mailgun. However, implementation would likely be very similar for other email service providers.

The ProMailer “Subscribe” page serves as the endpoint for webhooks when active. To enable and test Webhooks in ProMailer, follow the instructions below:

1. Install the webhooks file:

  • Copy the file /site/modules/ProMailer/promailer-webhooks.inc to your /site/templates/ directory.

  • The promailer-subscribe.php template file will include the file you copied to respond to webhook requests. This happens automatically.

  • The default promailer-webhooks.inc file included with ProMailer is setup to respond to Mailgun “bounce” and “spam-complaint” errors. However, the file can be modified to respond to other events or from other email service providers.

2. Login to your Mailgun (or other provider) account and locate the “Webhooks” section:

  • Add a webhook for “Permanent Failure” (aka bounce) to this endpoint URL: https://domain.com/promailer/?webhook=mailgun

  • Add a webhook for “Spam Complaint” to the same endpoint URL as above.

  • You’ll want to replace the “domain.com” above with your domain, the “/promailer/“ with the path to your Subscribe page (if different).

  • If not using Mailgun, you’ll want to replace the “mailgun” part of the URL at the end with a short name to identify your email service provider.

3. If not using Mailgun, you’ll need to modify the promailer-webhooks.inc file:

  • Non-Mailgun installations will need to modify this file to respond to webhooks from other service providers. You’ll want to do this using instructions from your email service provider. It may take some figuring-out, so feel free to seek help in the ProMailer support board. We will need a link to your service provider’s webhooks documentation page in order to help. For example, here is the one from Mailgun.

  • Over time we’ll hopefully have more promailer-webhooks.inc files setup for other email service providers available for download in the ProMailer support board. Stop by to check in.

4. Test out the bounce webhook:

  • Add an email address that you know will bounce (i.e. bounce@processwire.com) to your “test” subscribers list and send a message to this list.

  • Verify that the bounce was received by navigating in the admin to Setup > ProMailer > Subscriber Lists > your test list. In the “sort” selection box, select “most bounces”. You should see the bounced email address at the top, and a “bounce” column should appear, showing the number 1 (indicating one bounce).

  • If the webhook didn’t work, wait a couple minutes and try again. If still not working, stop by the ProMailer support board for help.

Terms, conditions, licenses, editions, usage

ProMailer VIP support

Your ProMailer service includes 1-year of VIP support through the ProcessWire support forum. Your account should be active upon completing your purchase. If for some reason it is not, please send a private message (PM) to "ryan", or contact us and let us know what your forum name is so that we can upgrade your member access. You must be logged in with the account you purchased ProMailer under in order to view the VIP support board.

If your support/upgrades period has expired

At any time in the future, if your VIP support has expired and you'd like to renew it, but don't see the option to do so, send a PM in the forums to me (ryan) and I can reset your renewal invoice to the current date.

ProMailer is Copyright 2019 by Ryan Cramer Design, LLC

Newest forum posts

Latest news

  • ProcessWire Weekly #533
    In the 533rd issue of ProcessWire Weekly we'll check out some newly released third party modules and highlight a new site of the week. Read on!
    Weekly.pw / 27 July 2024
  • Page List Custom Children module
    This simple module gives you the ability to customize the parent/child relationship as it appears in the admin page list, enabling child pages to appear under more than one parent.
    Blog / 28 June 2024
  • Subscribe to weekly ProcessWire news

“ProcessWire is like a breath of fresh air. So powerful yet simple to build with and customise, and web editors love it too.” —Margaret Chatwin, Web developer