Skip to main content

EmailOctopus Destination

Nexla's bi-directional connectors allow data to flow both to and from any location, making it simple to create a FlexFlow data flow that sends data to an EmailOctopus destination.
email_octopus_api.png

EmailOctopus

Create an EmailOctopus Destination​

  1. Click the + icon on the Nexset that will be sent to the EmailOctopus destination, and select the Send to Destination option from the menu.

  2. Select the EmailOctopus connector from the list of available destination 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 destinations can be created using pre-built endpoint templates, which expedite destination setup for common EmailOctopus write operations. Each template is designed specifically for the corresponding EmailOctopus endpoint, making destination configuration easy and efficient.
    • To configure this destination using a template, follow the instructions in Configure Using a Template.

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

Configure Using a Template​

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

  • To configure this destination using a template, select the endpoint to which data will be sent from the Endpoint pulldown menu. Then, click on the template in the list below to expand it, and follow the instructions to configure additional endpoint settings.

    Start an Automation for a Contact

    Enqueues a contact into an EmailOctopus automation workflow. Use this endpoint to trigger drip sequences, onboarding workflows, or any other automation for specific contacts based on data arriving in Nexla — for example, triggering a welcome series when a new subscriber is added from a CRM.

    • Enter the unique identifier of the EmailOctopus automation you want to trigger in the Automation ID field. Automation IDs can be found in the EmailOctopus dashboard by navigating to Automations and opening the automation you want to use.

    • The request body must include the contact's email address. Nexla will map the appropriate Nexset field to the email_address property in the JSON payload sent to EmailOctopus.

    The contact must already exist in the EmailOctopus list associated with the automation before this endpoint can enqueue them. If the contact does not yet exist, use the Create Contact or Create or Update Contact endpoint first.

    Create Contact

    Creates a new contact record in a specific EmailOctopus mailing list. Use this endpoint to add new subscribers to a list from an external data source, such as a CRM, e-commerce platform, or sign-up form processor.

    • Enter the unique identifier of the EmailOctopus list to which you want to add the contact in the List ID field. List IDs can be found by running the List Contact Lists data source endpoint, or by navigating to your EmailOctopus account and opening the list.

    • The JSON payload sent to EmailOctopus must include the contact's email_address. Additional optional fields include fields (a JSON object of custom field values keyed by field tag), tags (an array of tag names), and status (either subscribed or unsubscribed).

    If the email address already exists in the list, the EmailOctopus API will return an error. To avoid errors when the contact may already exist, use the Create or Update Contact (upsert) endpoint instead.

    Create or Update Contact

    Creates a new contact or updates an existing contact in a specific EmailOctopus list (upsert operation). This is the recommended endpoint for syncing subscriber data from external sources, as it handles both new and existing contacts without returning an error for duplicates.

    • Enter the unique identifier of the EmailOctopus list in the List ID field. The upsert operation will either add a new contact or update the existing contact with the matching email address in this list.

    • The JSON payload must include the contact's email_address. Optional fields include fields (custom field values as a JSON object), tags (an array of tag names to assign), and status (subscribed or unsubscribed).

    When updating an existing contact, only the fields present in the request payload are modified. Fields not included in the payload retain their existing values. Tags provided in the request are added to the contact's existing tags rather than replacing them.

    Update Multiple List Contacts

    Updates multiple contacts in a specific EmailOctopus list in a single batch API call. Use this endpoint when you need to apply bulk changes to subscriber records — such as updating custom field values or subscription statuses across a large set of contacts.

    • Enter the unique identifier of the EmailOctopus list containing the contacts to update in the List ID field.

    • The JSON payload must be structured according to the EmailOctopus batch update format, which contains an array of contact objects. Each contact object must include email_address and the fields to update.

    Use the Record Batching options in the Manual Configuration section to group multiple Nexset records into a single batch payload when sending large volumes of updates. This reduces the number of API calls and improves throughput.

    Update Contact

    Updates an existing contact's email address, custom field values, tags, or subscription status in a specific EmailOctopus list. Use this endpoint to keep subscriber profiles in sync with changes made in external systems such as CRMs or data warehouses.

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

    • Enter the unique identifier of the contact to update in the Contact ID field. Contact IDs can be retrieved using the Get Contacts data source endpoint.

    • The JSON payload may include any combination of the following updateable fields: email_address, fields (custom field values), tags, and status.

    Delete Contact

    Permanently removes a contact from a specific EmailOctopus list. Use this endpoint when contacts should be fully removed from a list — for example, to process deletion requests for GDPR or CCPA compliance.

    • Enter the unique identifier of the EmailOctopus list from which the contact should be removed in the List ID field.

    • Enter the unique identifier of the contact to delete in the Contact ID field. Contact IDs can be retrieved using the Get Contacts data source endpoint.

    Deleting a contact from a list is permanent and cannot be undone. If you want to prevent a contact from receiving future emails without permanently deleting their record, consider updating their status to unsubscribed using the Update Contact endpoint instead.

    Create Field

    Creates a new custom contact field in a specific EmailOctopus list. Custom fields allow you to store additional subscriber attributes beyond the default email address — such as first name, last name, date of birth, or any other data relevant to your audience.

    • Enter the unique identifier of the EmailOctopus list in which the new custom field should be created in the List ID field.

    • The JSON payload must specify the field label (the display name) and type (the data type, such as TEXT, NUMBER, DATE, or URL).

    Update Field

    Updates the label or other properties of an existing custom contact field in a specific EmailOctopus list. Use this endpoint to rename or reconfigure fields as your data model evolves.

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

    • Enter the tag identifier of the field to update in the Field Tag field. Field tags are system-generated identifiers (e.g., FirstName or DateOfBirth) assigned when a field is created. They can be found in the EmailOctopus list settings or via the Get List data source endpoint.

    Delete Field

    Permanently removes a custom contact field from a specific EmailOctopus list. Use this endpoint to clean up obsolete fields that are no longer needed.

    • Enter the unique identifier of the EmailOctopus list from which the field should be removed in the List ID field.

    • Enter the tag identifier of the field to delete in the Field Tag field.

    :::warning Important Deleting a custom field permanently removes the field definition and all associated data stored in that field for every contact in the list. This action cannot be undone. :::

    Create List

    Creates a new mailing list in your EmailOctopus account. Use this endpoint to programmatically provision new lists — for example, when setting up list-per-segment or list-per-product structures from an automated pipeline.

    • The JSON payload must include the name property, which sets the display name of the new list.
    • No additional path parameters are required for this endpoint.

    Update List

    Updates the name or other properties of an existing EmailOctopus mailing list. Use this endpoint to rename lists as part of an automated list management workflow.

    • Enter the unique identifier of the list to update in the List ID field. List IDs can be obtained from the List Contact Lists data source endpoint.

    • The JSON payload should include the name property with the new list name.

    Delete a List

    Permanently deletes an EmailOctopus mailing list and all contacts, fields, and associated data within it. Use this endpoint with care — only when a list and all of its data should be completely removed from your EmailOctopus account.

    • Enter the unique identifier of the list to delete in the Id field. List IDs can be obtained from the List Contact Lists data source endpoint.

    :::warning Important Deleting a list permanently removes the list and all subscriber data within it. This action cannot be undone. Ensure that all valuable contact data has been exported before proceeding. :::

    Create Tag

    Creates a new tag within a specific EmailOctopus list. Tags are labels that can be assigned to contacts to enable segmentation, filtering, and targeted automation. Use this endpoint to programmatically create tag definitions for new use cases.

    • Enter the unique identifier of the EmailOctopus list in which the tag should be created in the Id field.

    • The JSON payload must include the name property specifying the tag name.

    Update Tag

    Updates the name or properties of an existing tag in a specific EmailOctopus list. Use this endpoint to rename tags as part of a list management or data governance workflow.

    • Enter the unique identifier of the EmailOctopus list containing the tag in the List Id field.

    • Enter the current name of the tag to update in the Tag field.

    • The JSON payload should include the updated name property for the tag.

    Delete Tag

    Permanently deletes a tag from a specific EmailOctopus list. Deleting a tag removes it from all contacts in the list to which it was assigned. Use this endpoint to clean up obsolete tags.

    • Enter the unique identifier of the EmailOctopus list from which the tag should be removed in the List Id field.

    • Enter the name of the tag to delete in the Tag Name field.

Configure Manually​

EmailOctopus destinations can be manually configured to send data to any valid EmailOctopus API endpoint.

Using manual configuration, you can also configure Nexla to automatically send the response received from the EmailOctopus API after each call to a new Nexla webhook data source, enabling downstream processing of API responses.

API Method​

  1. To manually configure this destination, 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. Common methods for EmailOctopus write operations include:

    • POST: For creating new resources (contacts, lists, fields, tags)
    • PUT: For updating or upserting existing resources
    • DELETE: For removing resources such as contacts, fields, tags, or lists

Data Format​

  1. Select the format in which the Nexset data will be sent to the EmailOctopus API from the Content Format pulldown menu. EmailOctopus accepts JSON as the primary data format. Nexla will automatically convert the data to the selected format for each API call.

API Endpoint URL​

  1. Enter the URL of the EmailOctopus API endpoint to which you want to send the Nexset data in the URL field. All EmailOctopus write endpoints begin with https://api.emailoctopus.com/. For example:
    • https://api.emailoctopus.com/lists/{list_id}/contacts — to create or upsert a contact
    • https://api.emailoctopus.com/lists/{list_id}/contacts/{contact_id} — to update or delete a specific contact

Request Headers​

Optional

  • If Nexla should include any additional request headers in API calls to this destination, 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 — this is handled automatically by Nexla using your saved EmailOctopus credential. For JSON payloads, including Content-Type:application/json as an additional header is recommended if not already applied by default.

Exclude Attributes from the Call​

Optional

  • If any record attributes in the Nexset should be omitted when sending data to this EmailOctopus destination, select the attributes from the Exclude Attributes pulldown menu.

  • Any number of attributes can be selected for exclusion, and all excluded attributes will be shown in the field. To remove an attribute from the list, click the X icon next to the attribute name.

Record Batching​

Optional

  1. If records should be sent to this destination in batched API calls, check the box next to Would you like to batch your records together? to enable record batching.

  2. Enter the maximum number of records that should be batched together in a single API call in the Batch Size field. By default, this value is set to 100.

  3. Select the algorithm that will be used to group records into batches from the Grouping Algorithm pulldown menu. The sample request shown in the panel on the right will be updated to reflect the current batching settings. Some algorithms require additional settings—click on an algorithm listed below to view instructions for configuring these settings.

Property Inside JSON Object

  1. Enter the name of the JSON property that should contain the batched records in the Property Name field.
  2. If any additional properties should be included in the request, enter the properties in the Other Props field in JSON format.

Code

  1. Enter the code that will be used to create the batched request in the code editor below the Grouping Algorithm field.

Response Webhook​

Optional

Nexla can automatically send the response received from the EmailOctopus API after each call to a new Nexla webhook data source. This option allows you to keep track of the status of each API call and any additional information returned after each call.

  • To enable this option, check the box next to Would you like to process the API response as a Nexla Webhook source?.

Sample Request Payload​

Sample request payloads containing a portion of the Nexset data that will be sent to the EmailOctopus API endpoint based on the current settings are shown in the Sample Payload panel on the right. These samples can be referenced to ensure that the destination and request settings are correctly configured.

  • Click on a sample request payload to expand it and view the complete payload content.
  • Sample payloads are automatically updated with each setting change, making it easy to verify that changes achieve the desired effect.

Endpoint Testing (Manual Configuration)​

After all endpoint settings have been configured, Nexla can send a test payload to the EmailOctopus API to ensure that the destination is configured correctly.

  1. To send a test payload, select the Test button at the top of the Sample Payload panel, and click on a listed sample payload to expand it.

  2. If any modifications to the sample payload are needed, make the necessary changes directly within the sample window.

  3. Click the Send Test Data button at the top of a sample payload to send the test payload to the EmailOctopus API using the current settings.

Save & Activate the Destination​

  • Once all endpoint settings have been configured, click the Done button in the upper right corner of the screen to save and create the destination. To begin sending data to EmailOctopus, open the destination resource menu, and select Activate.

    The Nexset data will not be sent to EmailOctopus until the destination is activated. Destinations can be activated immediately or at a later time, providing full control over data movement.