You can export marketing and behavior signals from Connect to CSV. The files will be compressed into a gzip archive and uploaded to a secure SFTP directory allocated to your Connect subscription.

Running the mutation

If you haven't used our API before, see Using the Connect API for instructions. It explains how to authenticate your calls and suggests some tools for testing.

Daily usage limits

• Total data jobs: 20
• Total output size: 1GB
• Total rows unloaded: 2 million

If any of these limits is reached, the export operation becomes unavailable for the day.

Basic mutation structure

mutation {
  exportSignals(
    jobName: "July Email Engagement Export"
    export: {
      signals: {
        signalTypes: ["emailOpen", "emailClick", "emailDelivery"]
        timestampStart: "2025-07-01T00:00:00.000Z"
        timestampEnd: "2025-07-31T23:59:59.999Z"
      }
    }
    notifications: [{ channel: EMAIL, destination: "[email protected]" }]
  ) {
    dataJobId
    path
    fileFormat
  }
}

Mutation arguments

Export object

The export field contains the signals object with these required fields:

Signals object (all fields required)

• signalTypes: Array of strings - Types of signals to export (valid values: see Signal types below)
• timestampStart: DateTime string - Start of export period (ISO 8601 format)
• timestampEnd: DateTime string - End of export period (ISO 8601 format)

Signal types

Behavior signals

• addToCart - Adding products to the shopping cart
• browseAbandonment - Browsing products or categories without adding anything to the shopping cart
• cartAbandonment - Adding items to the shopping cart without completing the purchase
• error - Encountering an error on the site
• identification - Capture of visitors' emails or client/contact IDs
• onSiteSearch - Website search activity
• order - Order placement
• pageView - Page view events
• productConfiguration - Interactions on product pages
• productView - Product view events
• richMediaInteraction - Interactions with video and audio content

Marketing signals

Email:

• emailClick - Email link clicks
• emailDelivery - Successful email deliveries
• emailFailure - Email delivery failures
• emailInbound - Inbound email responses
• emailOpen - Email opens
• emailSend - Email send events

SMS:

• smsClick - SMS link clicks
• smsDelivery - Successful SMS deliveries
• smsFailure - SMS delivery failures
• smsInbound - Inbound SMS responses
• smsSend - SMS send events

WhatsApp:

• whatsAppClick - WhatsApp link clicks
• whatsAppDelivery - Successful WhatsApp deliveries
• whatsAppFailure - WhatsApp delivery failures
• whatsAppInbound - Inbound WhatsApp responses
• whatsAppOpen - WhatsApp message opens
• whatsAppSend - WhatsApp send events

Notifications object

• channel (required): Enum - Notification delivery channel (valid values: EMAIL)
• destination (required): String - Email address for notifications

Custom file placement (optional)

The to object contains the sftp object with two approaches for file placement:

Approach 1: Using parentFolder and namingPrefix

• parentFolder: String - Custom subdirectory (must start with Export/Signals)
  • Allowed characters: alphanumeric, spaces, hyphens (-), underscores (_), slashes (/)
  • Example: Export/Signals/Test
• namingPrefix: String - Custom prefix added to the file name Signals_Export.csv

Approach 2: Using path

Use this approach when you need full control over the file path and name.

• path: String - Complete file path on SFTP server (relative to subscription directory)
  • Must be unique and include the file name with the .csv extension.
  • Cannot be combined with parentFolder or namingPrefix.
  • Example: Behavior Signals/Order/Demo_Export.csv

Response fields

• dataJobId (required): String - Export job ID (use this to track status in Connect)
• fileFormat (required): String - Export file format (valid values: CSV)
• path (required): String - File path on SFTP server (relative to subscription directory).

Export process workflow

Step 1: Job monitoring

1. Log in to Acoustic Connect.
2. Navigate to Data management > Job monitoring.
3. Find your export job on the Job status tab.

📘

Note

Processing typically takes several minutes.

Step 2: SFTP server access setup

You need this step if you haven't accessed our SFTP server before.

1. Generate SSH keys

ssh-keygen -t ed25519 -C "Acoustic Connect key" -f key

This creates two files: key (private) and key.pub (public)

🚧

Warning

For security reasons, don't share the private key with anyone.

2. Register public key

Run the following mutation to register your public key in the API. Replace "YOUR_PUBLIC_KEY" with the content from key.pub:

mutation updatePublicKey {
  updatePublicKeyForConnectUser(
    publicKey: "YOUR_PUBLIC_KEY"
  ) {
    publicKey
  }
}

SFTP connection settings

• Protocol: SFTP – SSH File Transfer Protocol
• Port: 22
• Logon type: Key file
• Key file: Path to your private key file
• User: Your Acoustic Connect email address
  • Requirements: 3-100 characters, Latin letters, numbers 0-9, underscores (_), hyphens (-), periods (.)
  • Not allowed: plus (+), quotes ("), or other special characters

SFTP hosts by region

Step 3: File collection

Access files via SFTP server.

Notes:

• Files are grouped by date.
• Files are automatically deleted after 28 days.
• You cannot delete or rename the default /Export/Signals/ directory (it's reserved for export tasks).

Export data structure

The CSV export contains the following columns (grouped below for convenience).

Common data (all signal types)

• DATASET_ID: Text - Your audience ID
• SUBSCRIPTION_ID: Text - Your Connect subscription ID
• TEMPORARY_LINKING_ID: Text - Temporary ID linking audience with signal data

Behavior signal data

• ACOUSTIC_APP_KEY: Text - Your application identifier in Connect
• CATEGORY: Text - Signal category (valid values: Behavior, Marketing)
• DESCRIPTION: Text - Signal description
• NAME: Text - Signal name
• OBSERVED_TIMESTAMP: DateTime text - When Connect processed signal making it available for analytics (UTC, ISO 8601) - Example: 2025-08-31T08:29:30.001Z
• RECEIVED_TIMESTAMP: DateTime text - When Connect received signal (UTC, ISO 8601) - Example: 2025-08-31T08:29:30.001Z
• SIGNAL_CONTENT: JSON - Raw signal content containing the complete signal payload with all signal-specific fields (for details on signal-specific field structures, see Prepare signal content for import)
• SIGNAL_GROUP: Text - Signal grouping identifier (valid values: session, page, order, cart, product)
• SIGNAL_TIMESTAMP: DateTime text - When signal happened (UTC, ISO 8601) - Example: 2025-08-31T08:29:30.001Z
• SCREEN_VIEW_NAME: Text - Most recent screen view when a behavior signal happens
• TLTSID: Text - The UUID portion of the session ID (generated by the Connect library)

Marketing signal data

Signal metadata

• BOT_DETECTED: Boolean - Whether click was detected as bot traffic
• BOT_DETECTION_REASON: Text - Reason for bot classification (valid values: APPLE_MPP, DELIVERY_OPEN_THRESHOLD, OPEN_COUNT_THRESHOLD, CLICK_COUNT_THRESHOLD, OPEN_CLICK_THRESHOLD, CLICK_TIME_THRESHOLD, USER_AGENT)
• CLASSIFICATION: Text - Type of inbound message or failure (valid values: PERMANENT, TEMPORARY, UNSUBSCRIBE, ABUSE, CHANGE_OF_ADDRESS, DOI_CONFIRM, OTHER)
• CLASSIFICATION_CODE: Text - Additional classification detail (valid values: BAD_CONTENT, BAD_RECIPIENT, BAD_RELAY, BAD_SENDER, OTHER, RESTRICTION, SYSTEM)
• MESSAGE_SIGNAL_ID: Text - The ID of a signal triggered by a click on a link from a marketing campaign. It lets you map behavioral signals to their originating message signals for conversion activity tracking.
• SIGNAL_ID: Text - Unique signal identifier
• SIGNAL_TYPE: Text - Type of signal (see Signal types above)
• TIMESTAMP: DateTime text - When signal was received (UTC, ISO 8601)

Contact data

• Addressable attributes: Text - Separate column for each addressable contact attribute (email, phone)
• CONSENT_EMAIL: Text - Email consent status (valid values: OPT_IN, OPT_OUT, OPT_IN_UNVERIFIED)
• CONSENT_SMS: Text - SMS consent status (valid values: OPT_IN, OPT_OUT, OPT_IN_UNVERIFIED)
• CONSENT_WHATSAPP: Text - WhatsApp consent status (valid values: OPT_IN, OPT_OUT, OPT_IN_UNVERIFIED)
• Non-addressable attributes: Various - All other audience attributes including Contact key

Campaign data

• CAMPAIGN_DESCRIPTION: Text - User-defined description of the marketing campaign that the message originates from
• CAMPAIGN_ID: Text - Unique identifier of the marketing campaign that the message originates from
• CAMPAIGN_NAME: Text - Campaign name
• CAMPAIGN_STATUS: Text - Current campaign status
  • RUNNING: Active campaign mailings
  • COMPLETED: Completed campaign mailings
  • CANCELLED: Canceled campaign mailings
  • TEMPLATE: Mailings that use content retrieval
• CAMPAIGN_TYPE: Text - Campaign type (valid values: SCHEDULED, TRIGGERED, MULTISTEP)
• COMPLETED_DATE: DateTime text - Campaign completion date (ISO 8601)
• CONSENT_GROUP_ID: Text - Consent group ID used for the send
• ENTRY_SIGNAL: Text - Signal used as entrance criteria for triggered/multistep campaigns
• ENTRY_TYPE: Text - How contacts enter campaign (valid values: SEGMENT, SIGNAL)
• FREQUENCY: Text - Campaign frequency (valid values: ALWAYS ON, ONE TIME)
• SCHEDULED_DATE: DateTime text - Campaign scheduled/start date (ISO 8601)
• SEGMENT_DEFINITION_ID: Text - Segment definition ID
• SEGMENT_ID: Text - Segment ID for scheduled campaigns
• TAGS: Array of text - Campaign tags

Message data

Core message fields:

• MESSAGE_ID: Text - Published message ID
• MESSAGE_NAME: Text - Message name
• MESSAGE_TAGS: Array of text - Message tags

Link data:

• LINK_ID: Text - Clicked link ID

Personalization data:

• AUDIENCE_VARIABLES: Array of text - Variables from audience data
• PERSONALIZATION_VARIABLES: Array of text - All variable datasets used for personalization
• PLACEHOLDER_VARIABLES: Array of text - Variables included in message
• PRODUCT_VARIABLES: Array of text - Variables from product catalog
• REFERENCE_SET_VARIABLES: Array of text - Variables from reference set

Email-specific fields:

• EMAIL_FROM_ADDRESS: Text - Sender email address
• EMAIL_FROM_NAME: Text - Sender display name
• EMAIL_PRE_HEADER: Text - Preview text after subject line
• EMAIL_REPLY_TO_ADDRESS: Text - Reply-to address
• EMAIL_SUBJECT: Text - Email subject line
• EMAIL_TAGS: Array of text - Email-specific tags
• EMAIL_TRACKING_LEVEL: Text - Tracking level (valid values: no_tracking, aggregate, unique, opens_only)
• VMTA: Text - VirtualMTA selected for message
• VMTA_POOL: Text - VMTA pool for mailing

SMS-specific fields:

• INCLUDES_MEDIA: Boolean - Whether SMS includes media
• IS_MMS: Boolean - Whether SMS includes media content (making it MMS)
• SMS_TAGS: Array of text - SMS-specific tags

WhatsApp-specific fields

• INCLUDES_MEDIA: Boolean - Whether WhatsApp message includes media
• WHATSAPP_MESSAGE_BODY: Text - Non-personalized message body
• WHATSAPP_TAGS: Array of text - WhatsApp-specific tags
• WHATSAPP_TEMPLATE_CATEGORY: Text - Template category (valid values: Marketing, One-time password, Transactional)
• WHATSAPP_TEMPLATE_ID: Text - Template ID
• WHATSAPP_TEMPLATE_NAME: Text - Template name
• WHATSAPP_TYPE: Text - Message type (valid values: Custom, Templated)

Example usage

Export all SMS signals (using path)

mutation {
  exportSignals(
    jobName: "SMS Signals - Q3 2025"
    export: {
      signals: {
        signalTypes: ["smsSend", "smsDelivery", "smsFailure", "smsClick"]
        timestampStart: "2025-07-01T00:00:00.000Z"
        timestampEnd: "2025-09-30T23:59:59.999Z"
      }
    }
    to: {
      sftp: {
        path: "SMS_Reports/Q3_2025/SMS_Signals_Export.csv"
      }
    }
  ) {
    dataJobId
    path
    fileFormat
  }
}

Export shopping funnel signals (using parentFolder + namingPrefix)

mutation {
  exportSignals(
    jobName: "Shopping Funnel Analysis - August 2025"
    export: {
      signals: {
        signalTypes: ["addToCart", "cartAbandonment", "browseAbandonment", "order"]
        timestampStart: "2025-08-01T00:00:00.000Z"
        timestampEnd: "2025-08-31T23:59:59.999Z"
      }
    }
    to: {
      sftp: {
        parentFolder: "Export/Signals/Shopping_Funnel"
        namingPrefix: "August_2025_"
      }
    }
    notifications: [
      { 
        channel: EMAIL, 
        destination: "[email protected]" 
      }
    ]
  ) {
    dataJobId
    path
    fileFormat
  }
}

Export product engagement signals (using path)

mutation {
  exportSignals(
    jobName: "Product Engagement Q3 2025"
    export: {
      signals: {
        signalTypes: ["productView", "productConfiguration", "richMediaInteraction", "onSiteSearch"]
        timestampStart: "2025-07-01T00:00:00.000Z"
        timestampEnd: "2025-09-30T23:59:59.999Z"
      }
    }
    to: {
      sftp: {
        path: "Behavior_Signals/Product_Engagement/Q3_2025_Export.csv"
      }
    }
  ) {
    dataJobId
    path
    fileFormat
  }
}