EO4WP: EmailOctopus for WordPress

Use the email marketing software EmailOctopus and your website to collect newsletter subscriptions. With our plugin you can integrate EmailOctopus in different ways:

• Using a subscription form in the WordPress Block Editor
• Via the checkout page of your webshop with WooCommerce
• Using a form widget in Elementor Pro
• Place a form on every page using a shortcode

Do you need support for this plugin? Please post your question via the plugin support forum at wordpress.org.

General plugin installation

The installation of the plugin is the same as with any other plugin that you can install via the WordPress repository.

1. Go to Plugins > Add new plugin via your dashboard and search for “EO4WP”.
2. Install and activate the plugin that appears.

Before you go any further…

To further install the plugin, you need to create an EmailOctopus API key. Don’t have an EmailOctopus account yet? Follow this link and create a new account. With the free version of EmailOctopus you can add 2,500 subscribers and send 10,000 emails per month.

Once your account is active, you can also create an API key. Go to Integrations & API via the menu at the top right and then click Manage to the right from the list item named API. Then click the Create key button on the next page. Enter a descriptive name and click Create. Copy or download the API key via the pop-up that appears.

1. With the API key you now go to Settings > EO4WP. On this page, first paste the API key in the top field and click Save.
2. Now you can choose the default mailing list in the second options field. Do you use more than one list? You can always choose a different list for the different integrations.
3. The following fields are for integration with a shortcode.
   • Custom fields -If you want to use extra fields within your forms, enter them here. Enter the field name (the “Tag” value in EmailOctopus) and label per line.
   • Text for subscribe checkbox – The default text that appears next to the newsletter subscription box. You can read more about this option in the explanation of the shortcodes.
   • Include CSS – Check this to use the plugin’s CSS code. Uncheck this box if you only want to use the style of your theme.
   • Incl. JS/CSS sitewide – By default, these files are only added when the shortcode is used within a post or page. If you use a shortcode elsewhere, for example in the code of your theme, this check mark is necessary for the form to work.
   • GDPR text = Enter your own text/link for the GDPR field. Make sure that you do not delete or break the link HTML code.
   • Track in Google Analytics – Enter a value here for tracking an event in Google Analytics v4.
   • Track in Clicky – Create a Goal in Clicky and enter the goal ID here.

Are you using the integration for Elementor or WooCommerce? Then these settings do not apply. There are certainly other ways to track in Google Analytics or Clicky, but unfortunately the plugin currently does not support this.

Block Editor integration

The EmailOctopus form block allows you to add a subscription form directly from the WordPress Block Editor. The form uses the general plugin settings as defaults, while most options can be configured separately for each block.

1. Add the EmailOctopus form block to your page or post.

2. Select the EmailOctopus mailing list you want to use.

3. Enter the title, description and button label for your form.

4. Enable Newsletter checkbox if you want visitors to explicitly select a newsletter subscription option.

5. Enable Inline form to display the form fields and submit button on the same line. Disable this option for a regular vertical form.

6. Use Form fields only if you want to hide the title, description and privacy text.

Submission settings

The block also provides several optional settings that control how the subscription is processed:

Thank you text
Enter a custom message that is shown after a successful form submission.

Source
Add a source value to the subscriber in EmailOctopus. This can be useful to identify which form or page generated the subscription.

Tags
Add one or more tags to the subscriber. Use the same tag names as configured in EmailOctopus.

Reporting
Choose whether reporting is disabled, whether a report is sent together with the EmailOctopus subscription, or whether only the report should be sent.

The block uses the CSS and GDPR settings configured under Settings > EO4WP. Additional styling can be applied using the standard WordPress block CSS options.

WooCommerce integration

With the EmailOctopus integration for WooCommerce, it’s possible to enable a subscription option right on your checkout page. The integration works with the shortcode version and the “new” checkout block for WooCommerce.

For the configuration you need to follow these steps:

1. Goto WooCommerce > Settings > Integrations > EmailOctopus
2. Choose the Mailing list you prefer for the subscription feature on your checkout page.
3. Check the other features to include additional order information with each subscription. You can use this information in EmailOctopus for the segmentation of your mailing list(s).
   • Position – hoose where the newsletter subscription checkbox appears during checkout. The available positions depend on whether your store uses the classic checkout or the WooCommerce Checkout Block.
   • Subscription label – The text displayed next to the newsletter checkbox.
   • Store product categories – Adds the categories of purchased products as tags in EmailOctopus.
   • Store coupon – Adds a “coupon” tag when a coupon was used.
   • Last order – Stores the date of the customer’s latest order in EmailOctopus.
   • Submit language – Sends the order language to EmailOctopus, useful for multilingual stores.
   • Subscribe on order statuses – Choose which order statuses trigger the EmailOctopus subscription. Processing and Completed are selected by default. You can optionally include On hold and Pending payment.
4. Enable “Subscribe everyone” if you want to automatically subscribe customers without requiring them to select the newsletter checkbox. This can be useful for aftersales campaigns and other customer communication.

Elementor integration

If you use Elementor Pro, you can add EmailOctopus as an action to any Elementor form. The integration retrieves the available fields from your selected EmailOctopus mailing list, allowing you to map them directly to your Elementor form fields.

1. Create your Elementor form and select EmailOctopus under Actions After Submit.
2. Select the EmailOctopus mailing list you want to use.
3. Map the available EmailOctopus fields to the corresponding fields in your Elementor form.
4. If your form contains a separate newsletter subscription checkbox, use newsletter as the field ID. When the visitor selects this checkbox, EO4WP automatically adds the “newsletter” tag to the contact in EmailOctopus. This makes it possible to distinguish newsletter subscribers from contacts submitted for other purposes.
5. Optionally, enter one or more additional tags that should be added to subscribers submitted through this form.

Shortcode

With the plugin shortcode you can easily create a subscription form. The shortcode is useful for advanced implementations or when you want to place a subscription form outside the regular WordPress content. You can of course also use the shortcode together with Elementor or the block editor.

Shortcode attributes

title
The title above the form. Leave an empty value to not show a title. The default value is “Subscribe now!”

description
Use this attribute for a short description between the title and the form. The default value is “Subscribe today and get future blog posts your email.”

gdpr_text
This text with a link to your privacy statement is shown at the bottom of the form. By default this is retrieved via the settings page, but you can also enter your own text/link for each form.

btnlabel
The label for the submit button, the default value is “Subscribe”.

thank_you_text
Use this attribute for your own thank you text. If you do not use your own text, this standard texts will be used:
Including newsletter registration: Thanks, for joining our mailing list!

If you use only the reporting option: Thanks, for your interest.

report_only
This option has three settings:
y = Sends the report and processes the registration in EmailOctopus
o = Only sends the report via email
n = Disables the reporting function

btnclass
Enter the name of an additional CSS class here. You can then use this to format the button with your own CSS code.

listid
Enter a different mailing list ID here. You can find the ID in EmailOctopus via the Settings tab in the selected list. If you do not use the attribute, the default list from the plugin settings page will be used.

icon
If you have enabled the option for FontAwesome, you can specify 1 of several solid icons here. For example, “fa-arrow-down”. Visit the FontAwesome website and view all Solid Icons that are available with the free version. Have you already enabled FontAwesome via the theme? Then you might also be able to use icons from other FA series.

fsize
Is your theme based on the Bootstrap CSS framework? You can then use the value to determine how large the form fields and buttons should be. Possible values are “lg” or “sm”.

newsletter
Would you like to place a separate checkbox in your form for subscribing to the newsletter? Then enter a “y” for this attribute. By default this option is off.

container_class
This value is used for a CSS class at the outer DIV container created by the shortcode. Enter a value for this if you want to determine your own CSS style based on this.

form_class
If your theme supports the Bootstrap CSS framework, you can display a horizontal form with the default value “form-inline”. If you don’t want that, enter an empty value or your own CSS class name.

source
You can use the “source” field with the mailing list in EmailOctopus. The value you enter in the shortcode is then stored with the subscriber in EmailOctopus.

tags
Add comma separated tags. Use exact the same strings as in EmailOctopus.

extra_fields
This option allows you to add extra fields to your form. Please note, you can only use the field names (not labels) that you have entered in the plugin settings screen. The additional fields are shown after the email address field, in the same order as you enter them in the shortcode. Do you use “LastName” as an extra field? This will be shown between the first name and email address fields. 

hidden_fields
Do you want to add static information to your mailing list? This is possible with hidden fields. You enter the name and value for a hidden field as follows: name|value. You can enter multiple name/value combinations by separating them with a comma. Don’t forget to also create the fields in EmailOctopus.

clicky
Do you want to specify a separate goal for a form from Clicky? This can be done via this option. By default, the value you entered via the settings screen is used here or not if you haven’t entered a value before.

cookie_name
Do you want a cookie to be placed after sending a form? You can then specify the name for this cookie via this attribute. By default, a cookie named fw_eo_subscribed is created. The cookie has the value “yes” and is valid for 365 days.

form_only
With this option you can determine whether only the form is shown or also the title and text. By default this option is set to “n”. Set it to “y” if you want to show only the form.

You can place the shortcode via the shortcode block of the Block Editor, via the Classic Editor or via the Elementor shortcode widget.

For developers

The plugin currently has several filter hooks that allow you to manipulate the behavior of the plugin. Check the examples below the information.

fweo_emailoctopus_show_static
Use this hook to display the static plugin files on specific pages.

fweo_add_extra_data_fields
With this hook you can add extra fields/values to a subscription.

fweo_emailoctopus_extra_form_html
Add additional form fields to your subscribe form. Just add the HTML and use EO field name as name attribute. 

fweo_emailoctopus_extra_fields
Register the name attribute and label for the form HTML code you add via the hook “fweo_emailoctopus_extra_form_html”.

fweo_emailoctopus_hidden_fields
Add additional key/value pairs to add your own hidden form fields to a subscribe form.

fweo_emailoctopus_form_class
Add additional class names to the form element.

fw_eo_newsletter_tag
The filter allows you to customize the tag that is added to EmailOctopus contacts when they subscribe to the newsletter.