Skip to main content

EmailOctopus Data Source

The EmailOctopus connector enables you to ingest campaign data, contact records, list details, tag information, and engagement reports from your EmailOctopus account into Nexla data flows. Follow the instructions below to create a new data flow that ingests data from an EmailOctopus source in Nexla.
email_octopus_api.png

EmailOctopus

Create a New Data Flow​

  1. To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Then, select the desired flow type from the list, and click the Create button.

  2. Select the EmailOctopus connector tile from the list of available connectors. Then, select the credential that will be used to connect to the EmailOctopus account, and click Next; or, create a new EmailOctopus credential for use in this flow.

  3. In Nexla, EmailOctopus data sources can be created using pre-built endpoint templates, which expedite source setup for common EmailOctopus API endpoints. Each template is designed specifically for the corresponding EmailOctopus endpoint, making source configuration easy and efficient.
    • To configure this source using a template, follow the instructions in Configure Using a Template.

    EmailOctopus sources can also be configured manually, allowing you to ingest data from EmailOctopus endpoints not included in the pre-built templates or apply further customizations to exactly suit your needs.
    • To configure this source manually, follow the instructions in Configure Manually.

Configure Using a Template​

Nexla provides pre-built templates that can be used to rapidly configure data sources to ingest data from common EmailOctopus endpoints. Each template is designed specifically for the corresponding EmailOctopus endpoint, making data source setup easy and efficient.

Endpoint Settings​

  • Select the endpoint from which this source will fetch data from the Endpoint pulldown menu. Available endpoint templates are listed in the expandable boxes below. Click on an endpoint to see more information about it and how to configure your data source for this endpoint.

List Campaigns

Retrieves a paginated list of all campaigns in your EmailOctopus account. Use this endpoint to pull campaign metadata such as names, statuses, subjects, and creation dates for reporting or auditing purposes.

  • This endpoint returns all campaigns in your account and supports cursor-based pagination, so Nexla will automatically fetch additional pages until all campaigns have been retrieved.

  • Optionally, enter a value in the Limit field to control the maximum number of campaigns returned per page. When left blank, the EmailOctopus API applies its default page size.

This endpoint returns campaign-level metadata. To retrieve contact-level engagement data such as opens, clicks, bounces, or unsubscribes for a specific campaign, use one of the campaign report endpoints such as Campaign Contact Reports, Campaign Links Report, or Campaign Summary Report.

List Contact Lists

Retrieves a paginated list of all contact lists (also called mailing lists or audiences) in your EmailOctopus account. Use this endpoint to enumerate available lists and their metadata, such as names, IDs, and subscriber counts.

  • This endpoint automatically paginates through all contact lists in your account. Nexla will continue fetching pages until all lists have been retrieved.

  • Optionally, enter a value in the Limit field to control the maximum number of lists returned per page.

List IDs returned by this endpoint are required by several other endpoints, such as Get Contacts and Get List. Note these IDs when building multi-step data flows that pull contact-level data from specific lists.

Get Campaign

Retrieves the full details of a single campaign by its unique identifier. Use this endpoint when you need metadata for one specific campaign rather than paginating through all campaigns.

  • Enter the unique identifier of the campaign you want to retrieve in the Campaign ID field. Campaign IDs can be found by first running the List Campaigns endpoint.

This endpoint returns a single JSON object representing the campaign, not an array. Nexla reads the response at the root path ($) and will produce a single-record Nexset for each run.

Campaign Contact Reports

Returns a paginated list of per-contact engagement records for a specific campaign. Each record indicates how an individual contact interacted with the campaign — for example, whether they opened it, clicked a link, bounced, complained, or unsubscribed.

  • Enter the unique identifier of the campaign whose contact reports you want to retrieve in the Campaign ID field. Campaign IDs can be obtained from the List Campaigns or Get Campaign endpoints.

  • Optionally, enter a value in the Limit field to control the maximum number of contact report records returned per page.

  • Optionally, enter a contact engagement status in the Status field to filter the results. Valid status values include:

    • opened — contacts who opened the campaign
    • clicked — contacts who clicked a link in the campaign
    • bounced — contacts whose email address bounced
    • complained — contacts who marked the campaign as spam
    • unsubscribed — contacts who unsubscribed after receiving the campaign

Leave the Status field blank to retrieve records for contacts with any engagement status. Nexla uses cursor-based pagination to automatically retrieve all pages until no further records remain.

Campaign Links Report

Retrieves link click statistics for all links included in a specific campaign. Use this endpoint to analyze which links in a campaign received the most engagement, supporting click-through rate analysis and campaign optimization.

  • Enter the unique identifier of the campaign for which you want link click statistics in the Campaign ID field. Campaign IDs can be obtained from the List Campaigns or Get Campaign endpoints.

  • This endpoint is not paginated and returns all link report data for the specified campaign in a single response.

Campaign Summary Report

Retrieves aggregated summary statistics for a specific campaign, including total counts for opens, unique opens, clicks, unique clicks, bounces, complaints, and unsubscribes. Use this endpoint for high-level campaign performance reporting.

  • Enter the unique identifier of the campaign for which you want the summary report in the Campaign ID field. Campaign IDs can be obtained from the List Campaigns or Get Campaign endpoints.

  • This endpoint returns a single summary object for the specified campaign and is not paginated.

For contact-level engagement detail (individual records per contact), use the Campaign Contact Reports endpoint instead. The Campaign Summary Report provides roll-up totals only.

Get Contacts

Returns a paginated list of all contacts in a specific mailing list, with support for filtering by subscription status, tag, and creation or update timestamps. Use this endpoint to export subscriber data for analysis, synchronization with CRMs, or audience segmentation workflows.

  • Enter the unique identifier of the contact list from which you want to retrieve contacts in the List ID field. List IDs can be obtained from the List Contact Lists or Get List endpoints.

  • Optionally, enter a value in the Limit field to control the maximum number of contact records returned per page.

  • Optionally, filter results using any combination of the following fields:

    • Tag — Enter a tag name to retrieve only contacts that have been assigned that tag.
    • Status — Enter a subscription status to filter contacts. Common values include subscribed and unsubscribed.
    • Created Before — Enter an ISO 8601 timestamp (e.g., 2024-01-31T00:00:00+00:00) to retrieve only contacts created on or before that date and time.
    • Created After — Enter an ISO 8601 timestamp to retrieve only contacts created on or after that date and time.
    • Updated Before — Enter an ISO 8601 timestamp to retrieve only contacts last updated on or before that date and time.
    • Updated After — Enter an ISO 8601 timestamp to retrieve only contacts last updated on or after that date and time.

Nexla uses cursor-based pagination to automatically retrieve all pages of contact records. For incremental data loads, use the Created After or Updated After filters combined with Nexla date/time macros to fetch only new or recently changed contacts on each run.

Get Contact

Retrieves the full details of a single contact from a specific list by contact ID. Use this endpoint when you need to look up a specific subscriber's information including their email address, custom field values, tags, and subscription status.

  • Enter the unique identifier of the contact list containing the contact in the List ID field.

  • Enter the unique identifier of the contact you want to retrieve in the Contact ID field. Contact IDs can be obtained from the Get Contacts endpoint.

Get List

Retrieves the details of a single mailing list by its unique identifier, including its name, creation date, and field definitions. Use this endpoint to inspect the schema of a list before fetching its contacts.

  • Enter the unique identifier of the list you want to retrieve in the List ID field. List IDs can be obtained from the List Contact Lists endpoint.

Get All Tags

Returns a paginated list of all tags defined within a specific contact list. Tags in EmailOctopus are labels assigned to contacts to enable segmentation and targeted automation. Use this endpoint to enumerate available tags for a list.

  • Enter the unique identifier of the contact list whose tags you want to retrieve in the Id field.

  • Optionally, enter a value in the Limit field to control the maximum number of tags returned per page.

Get Bounced Contacts for a Campaign

Returns a paginated list of contacts whose email addresses bounced when a specific campaign was sent. Use this endpoint to identify and manage bounced addresses to maintain list hygiene and protect deliverability.

  • Enter the unique identifier of the campaign for which you want to retrieve bounced contact records in the Campaign ID field.

  • Optionally, enter a value in the Limit field to control the maximum number of records returned per page.

Get Contacts Who Clicked a Campaign Link

Returns a paginated list of contacts who clicked at least one link in a specific campaign. Use this endpoint to identify highly engaged subscribers for follow-up targeting or audience segmentation.

  • Enter the unique identifier of the campaign for which you want to retrieve click engagement records in the Campaign ID field.

  • Optionally, enter a value in the Limit field to control the maximum number of records returned per page.

Get Contacts Who Complained About a Campaign

Returns a paginated list of contacts who marked a specific campaign as spam. Use this endpoint to monitor complaint rates and remove or suppress complainers to protect your sender reputation.

  • Enter the unique identifier of the campaign for which you want to retrieve complaint records in the Campaign ID field.

  • Optionally, enter a value in the Limit field to control the maximum number of records returned per page.

Get Contacts Who Opened a Campaign

Returns a paginated list of contacts who opened a specific campaign. Use this endpoint to identify engaged subscribers and build segments for targeted follow-up campaigns or re-engagement workflows.

  • Enter the unique identifier of the campaign for which you want to retrieve open engagement records in the Campaign ID field.

  • Optionally, enter a value in the Limit field to control the maximum number of records returned per page.

Get Contacts Who Unsubscribed After a Campaign

Returns a paginated list of contacts who unsubscribed from your list after receiving a specific campaign. Use this endpoint to track unsubscribe events, analyze campaign-driven churn, and keep downstream systems in sync with your EmailOctopus subscription status.

  • Enter the unique identifier of the campaign for which you want to retrieve unsubscribe records in the Campaign ID field.

  • Optionally, enter a value in the Limit field to control the maximum number of records returned per page.

Endpoint Testing​

Once the selected endpoint template has been configured, Nexla can retrieve a sample of the data that will be fetched according to the current settings. This allows users to verify that the source is configured correctly before saving.

  • To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.

  • If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.

Configure Manually​

EmailOctopus data sources can be manually configured to ingest data from any valid EmailOctopus API endpoint. Manual configuration provides maximum flexibility for accessing endpoints not covered by pre-built templates or when you need custom API configurations.

With manual configuration, you can also create more complex EmailOctopus sources, such as sources that use chained API calls or that apply custom filtering through query parameters.

API Method​

  1. To manually configure this source, select the Advanced tab at the top of the configuration screen.

  2. Select the API method that will be used for calls to the EmailOctopus API from the Method pulldown menu. All EmailOctopus data retrieval endpoints use:

    • GET: For retrieving campaigns, contacts, lists, tags, reports, and related data

API Endpoint URL​

  1. Enter the URL of the EmailOctopus API endpoint from which this source will fetch data in the Set API URL field. All EmailOctopus API endpoints begin with https://api.emailoctopus.com/. For example:
    • https://api.emailoctopus.com/campaigns — to list all campaigns
    • https://api.emailoctopus.com/lists — to list all contact lists
    • https://api.emailoctopus.com/lists/{list_id}/contacts — to retrieve contacts from a specific list

The EmailOctopus API automatically authenticates requests using the Bearer token from your saved credential. You do not need to include the API key in the URL or as a query parameter. For complete API endpoint documentation, see the EmailOctopus API documentation.

Date/Time Macros (API URL)​

Optional

Optionally, the API URL can be customized using macros—all macros added to the API URL will be converted into values when Nexla executes the API call. Macros are dynamic placeholders that allow you to create flexible API endpoints that can adapt to different time periods or data requirements.

Macros are useful for EmailOctopus endpoints that accept date-range parameters, such as filtering contacts by created_at or last_updated_at timestamps. For example, you can use {now-1} to construct a URL that always retrieves contacts updated within the last time unit.

  1. To add a macro, type { at the appropriate position in the API URL (within the Set API URL field), and select the desired macro from the dropdown list.

    • {now} – The current datetime
    • {now-1} – The datetime one time unit before the current datetime
    • {now+1} – The datetime one time unit after the current datetime
    • custom – Datetime macros can reference any number of time units before or after the current datetime—for example, enter (now-4) to indicate the datetime four time units before the current datetime

  2. Select the format that will be applied to datetime macros from the Date Format for Date/Time Macro pulldown menu. This format will be applied to the base datetime value of the macro—i.e., the value of {now} in {now-1}.

  3. Select the datetime unit that will be used to perform mathematical operations in the included macro(s) from the Time Unit for Operations pulldown menu—for example, for the macro {now-1}, when Day is selected, {now-1} will be converted to the datetime one day before the current datetime.

Lookup-Based Macros (API URL)​

Optional

Column values from existing lookups can also be included as macros in the API URL. Lookup-based macros allow you to reference data from previously configured data sources or lookups, enabling dynamic API endpoints that adapt based on existing data.

Lookup-based macros are useful when you need to parameterize EmailOctopus API endpoints with values from other Nexla sources — for example, dynamically passing a list ID or campaign ID retrieved from another source.

  1. To include a lookup column value macro, select the relevant lookup from the Add Lookups to Supported Macros pulldown menu.

  2. Type { at the appropriate position in the API URL, and select the lookup column-based macro from the dropdown list. Lookup-based macros are automatically populated into the macro list when a lookup is selected in the Add Lookups to Supported Macros pulldown menu.

Path to Data​

Optional

If only a subset of the data returned by the EmailOctopus API endpoint is needed, you can designate the part(s) of the response that should be included in the Nexset(s) produced from this source by specifying the path to the relevant data within the response.

For example, most EmailOctopus list-type endpoints return a JSON response with a top-level data array containing the actual records, alongside a paging object with pagination metadata. Specifying $.data[*] as the path to data instructs Nexla to treat each element in the data array as a separate record.

Path to Data is important for EmailOctopus endpoints that return paginated responses, as the records are typically nested inside a data array. Without specifying the correct path, Nexla may not be able to properly parse and organize the response into usable records.

  • To specify which data should be treated as relevant in responses from this source, enter the path to the relevant data in the Set Path to Data in Response field.

    • For responses in JSON format, enter the JSON path that points to the object or array that should be treated as relevant data. JSON paths use dot notation (e.g., $.data[*] to access an array of items within a top-level data property, or $ to treat the entire response as a single record).
    Path to Data Example:

    For EmailOctopus endpoints that return a list of records (such as List Campaigns or Get Contacts), enter $.data[*] to extract each element in the data array as a separate record. For endpoints that return a single object (such as Get Campaign or Campaign Summary Report), enter $ to use the entire response as a single record.

Autogenerate Path Suggestions​

Nexla can also autogenerate data path suggestions based on the response from the API endpoint. These suggested paths can be used as-is or modified to exactly suit your needs.

  • To use this feature, click the Test button next to the Set API URL field to fetch a sample response from the API endpoint. Suggested data paths generated based on the content & format of the response will be displayed in the Suggestions box below the Set Path to Data in Response field.

  • Click on a suggestion to automatically populate the Set Path to Data in Response field with the corresponding path. The populated path can be modified directly within the field if further customization is needed.

    PathSuggestions.png

Metadata​

If metadata is included in the response but is located outside of the defined path to relevant data, you can configure Nexla to include this data as common metadata in each record.

For example, EmailOctopus paginated responses include a paging object alongside the data array. If the data array is set as the path to data, you can optionally capture the paging metadata and attach it to each record produced from this source.

Metadata paths are useful for preserving contextual information from the EmailOctopus API response — such as pagination tokens or request timestamps — alongside each data record.

  • To specify the location of metadata that should be included with each record, enter the path to the relevant metadata in the Path to Metadata in Response field.

    • For responses in JSON format, enter the JSON path to the object or array that contains the metadata.

Request Headers​

Optional

  • If Nexla should include any additional request headers in API calls to this source, enter the headers & corresponding values as comma-separated pairs in the Request Headers field (e.g., header1:value1,header2:value2).

    You do not need to include an Authorization header or any other authentication header — these are handled automatically by Nexla using your saved EmailOctopus credential. The EmailOctopus API also accepts a Content-Type: application/json header for POST requests, but GET requests typically do not require additional headers.

Endpoint Testing​

After configuring all settings for the selected endpoint, Nexla can retrieve a sample of the data that will be fetched according to the current configuration. This allows users to verify that the source is configured correctly before saving.

  • To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.

  • If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.

Save & Activate the Source​

  1. Once all of the relevant steps in the above sections have been completed, click the Create button in the upper right corner of the screen to save and create the new EmailOctopus data source. Nexla will now begin ingesting data from the configured endpoint and will organize any data that it finds into one or more Nexsets.