Skip to main content
The EmailOctopus integration allows you to instantly route form respondents directly into your EmailOctopus subscriber lists. It supports deep custom field mapping (including numbers and dates) and gives you explicit control over double opt-in behavior.

​
Business Use Cases

Newsletter Signups

Automatically push new blog readers straight into your weekly digest list.

Lead Magnets

Trigger automated EmailOctopus drip campaigns the moment someone downloads your PDF.

Event Registration

Build a dedicated segment of webinar attendees with perfectly mapped custom demographic fields.

​
Step 1: Global Connection

Before you can push data to EmailOctopus, you must authorize Flex Forms to communicate with your account.
1

Locate your API Key

Log into your EmailOctopus dashboard. Navigate to Developer → API keys. Generate a new API v2 key (do not use legacy keys).
2

Establish the Connection

In your Flex Forms dashboard, open Integrations in the left rail (next to Global Settings). Locate the EmailOctopus card and enter your API Key.
3

Test and Verify

Click Save & Verify. Flex Forms will ping the https://api.emailoctopus.com endpoint to ensure the credentials are valid.

​
Step 2: Form-Level Configuration

Once the global connection is established, you must activate the integration on a per-form basis. Open your specific form in the Studio and navigate to the Integrations tab.

​
The Masterclass: Data Mapping

When mapping data from Flex Forms to EmailOctopus, the engine uses the internal Name of your form blocks. You do not need to manually hunt for List IDs; the system fetches your lists via live remote_select directly from the EmailOctopus API.
​
remote_select
required
Target List Loaded live from your EmailOctopus account. All new submissions will be added to this specific list.
​
select
default:"SUBSCRIBED"
Opt-In Status Control the subscription state of the new contact.
  • SUBSCRIBED: The contact is added immediately and can receive campaigns.
  • PENDING: Triggers the EmailOctopus double opt-in flow. Note: When the list uses double opt-in, EmailOctopus may still send a confirmation email regardless of this setting.
​
textarea
Custom Field Mapping Map your form block answers to EmailOctopus Custom Fields.Syntax: EmailOctopusFieldTag=form_field_name (One per line).Crucial Data Casting: The Flex Forms engine automatically casts Number fields to integers and Date fields to Y-m-d format to ensure they are accepted cleanly by the EmailOctopus API.Example Mapping:

​
Technical Resources & Troubleshooting

If you encounter issues where contacts are not appearing in your EmailOctopus lists, the issue is almost always a mismatch in Custom Field mapping syntax.
Inside your EmailOctopus list settings, view your Custom Fields. The “Tag” column (e.g., FirstName, CompanySize) is the exact string you must place on the left side of the = sign in the mapping text area.
Yes. If a respondent submits the form and their email address already exists in the selected EmailOctopus list, the engine will perform an update operation, refreshing their custom fields with the newest data.
For advanced architectural questions, refer to the official EmailOctopus API v2 Documentation.

​
Configuration Reference

​
Global Settings

​
password
required
EmailOctopus API Key Your master API key. Generate this in your EmailOctopus account settings.

​
Form-Level Settings

​
Subscriber Data

​
select
required
Email Field The primary email field for the subscriber.
​
select
First Name Field
​
select
Last Name Field

​
Field Mapping

​
textarea
Custom Fields Map your form blocks to EmailOctopus Custom Field Tags.Syntax: EmailOctopusTag=flex_forms_block_name
​
remote_select
Available fields (reference) A read-only helper to fetch live custom fields from EmailOctopus for mapping reference.
Last modified on September 7, 2026