Connection Types: FTP, SFTP, HTTP, Email & S3

Overview

The connection object is the part of your automation configuration that tells the engine how to reach the external system. Whether your vendor gives you an FTP server to download inventory files from, exposes a REST API, or sends data via email, the connection configuration handles the details of authenticating and transferring data.

Every automation requires a connection, and every connection requires a type. The type you choose determines which other fields are available. This guide covers each connection type in detail, with complete JSON examples and guidance on when to use each one.

Connection Features by Type

Not every connection type supports every operation. Before choosing a type, check what you need:

FTP

FTP (File Transfer Protocol) is the most common connection type for file-based vendor integrations. Many suppliers and distributors provide FTP credentials for exchanging inventory, catalog, and order files.

When to Use FTP

Your vendor gives you an FTP server address, username, and password. You need to download files from or upload files to their server.

Configuration Fields

Complete Example

"connection": {
    "type": "ftp",
    "address": "ftp.acmedistributor.com",
    "username": "{{ftp username}}",
    "password": "{{ftp password}}",
    "path": "/outbound/inventory",
    "port": 21
}

SFTP

SFTP (SSH File Transfer Protocol) works similarly to FTP but runs over an encrypted SSH connection. It is the preferred choice when security is a priority, and many modern vendors have moved exclusively to SFTP.

When to Use SFTP

Your vendor provides SFTP access (often on port 22) for secure file exchange. Some vendors may also provide an SSH key file instead of a password.

Configuration Fields

Complete Example

"connection": {
    "type": "sftp",
    "address": "sftp.vendor.com",
    "username": "{{sftp username}}",
    "password": "{{sftp password}}",
    "port": 22,
    "path": "/data/exports"
}

Key File Authentication

If your vendor provides an SSH private key instead of a password, paste the full key contents into the password parameter and set is_key_file to true:

"connection": {
    "type": "sftp",
    "address": "sftp.vendor.com",
    "username": "suredone_user",
    "password": "{{ssh key}}",
    "is_key_file": true,
    "path": "/data"
}

FTPS

FTPS (FTP over Explicit SSL) is a variant of FTP that adds SSL/TLS encryption. It has limited capabilities in the Automation Engine compared to standard FTP -- it supports downloading a single file only. You cannot use regex to match multiple files, and you cannot upload.

When to Use FTPS

Your vendor requires an explicit SSL connection and you only need to download a single named file.

Configuration Fields

Complete Example

"connection": {
    "type": "ftps",
    "address": "ftp.ekeystone.com",
    "username": "{{ftp username}}",
    "password": "{{ftp password}}",
    "path": "/outbound",
    "port": 990
}

HTTP / HTTPS

HTTP connections are for integrating with REST APIs. This is the most feature-rich connection type, supporting authentication flows, pagination, request chaining (triggers), and throttling. Use it whenever your vendor provides an API rather than file downloads.

When to Use HTTP

Your vendor has a REST API that returns JSON or XML data, or accepts data via HTTP POST/PUT requests.

Configuration Fields

Basic API Example

A simple GET request with an API key in the headers:

"connection": {
    "type": "http",
    "address": "https://api.vendor.com/v2/products",
    "method": "GET",
    "headers": {
        "Authorization": "Bearer {{api key}}",
        "Content-Type": "application/json",
        "Accept": "application/json"
    }
}

Login Flow

Some APIs require you to first authenticate by posting credentials to a login endpoint. The engine sends username and password to login_address, then uses the session/token from that response for the main request to address:

"connection": {
    "type": "http",
    "address": "https://www.vendor.com/export.php",
    "username": "{{api username}}",
    "password": "{{api password}}",
    "login_address": "https://www.vendor.com/user/login",
    "method": "POST",
    "headers": {
        "Host": "www.vendor.com"
    },
    "payload": {
        "stockExport": "items"
    }
}

If your login endpoint requires fields other than username and password, use login_credentials to define a custom login body:

"login_credentials": {
    "api_key": "{{vendor api key}}",
    "account_id": "{{account id}}",
    "grant_type": "api_key"
}

OAuth

For APIs that use OAuth 2.0, configure the oauth object inside the connection:

"connection": {
    "type": "http",
    "address": "https://api.vendor.com/v1/inventory",
    "method": "GET",
    "headers": {
        "Content-Type": "application/json"
    },
    "oauth": {
        "address": "https://api.vendor.com/v1/token",
        "method": "POST",
        "grant_type": "client_credentials",
        "client_id": "{{oauth client id}}",
        "client_secret": "{{oauth client secret}}"
    }
}

The engine obtains an access token automatically before making the main request. For advanced OAuth flows (authorization code grants, redirect-based flows), consult the advanced configuration guide.

Pagination

Many APIs return data across multiple pages. Enable pagination to automatically fetch all pages:

"connection": {
    "type": "http",
    "address": "https://api.vendor.com/v1/products",
    "method": "GET",
    "paginate": true,
    "pagination": {
        "next_token": "$.meta.next_page_url",
        "page_per_second": 2
    }
}

Throttling

To avoid hitting vendor rate limits, configure a throttle:

"connection": {
    "type": "http",
    "address": "https://api.vendor.com/v1/orders",
    "method": "POST",
    "throttle": {
        "request_limit": 5,
        "time_period": 1
    }
}

This limits the automation to 5 requests per second.

Complete HTTP Example

Here is a full HTTP connection that authenticates via OAuth, paginates results, and respects rate limits:

"connection": {
    "type": "http",
    "address": "https://api.turn14.com/v1/shipping/item_estimation",
    "method": "GET",
    "paginate": true,
    "headers": {
        "Content-Type": "application/json",
        "User-Agent": "SureDone/3.0"
    },
    "oauth": {
        "address": "https://api.turn14.com/v1/token",
        "method": "POST",
        "grant_type": "client_credentials",
        "client_id": "{{turn14_id}}",
        "client_secret": "{{turn14_secret}}"
    },
    "throttle": {
        "request_limit": 10,
        "time_period": 1
    }
}

Email

Email connections let your automation send data as email messages (for exports) or read data from email attachments (for imports). This is useful when a vendor or internal team communicates via email rather than through a server or API.

When to Use Email

Your vendor sends you inventory updates as email attachments, or you need to email order reports to a team or supplier who does not have an FTP server or API.

Configuration Fields for Exports (Sending Emails)

Configuration Fields for Imports (Reading Emails)

Email Search

The email_search object lets you narrow down which emails the automation processes. Common filters:

"email_search": {
    "unseen": true,
    "since": "-10 days",
    "subject": "Inventory Update",
    "from": "vendor@distributor.com"
}

Available search criteria include from, subject, body, to, cc, bcc, since, before, on, unseen, seen, new, recent, flagged, answered, and more.

Export Example (Sending an Order Email)

"connection": {
    "type": "email",
    "address": [
        "purchasing@vendor.com",
        "backup@vendor.com"
    ],
    "cc": "orders@yourstore.com",
    "subject": "Purchase Order {{oid}}",
    "body": "Please find the attached purchase order for order {{oid}}.",
    "send_as_attachment": true,
    "sender_name": "Your Store Ordering"
}

Import Example (Reading Vendor Emails)

"connection": {
    "type": "email",
    "address": "imap.gmail.com",
    "username": "{{email address}}",
    "password": "{{email password}}",
    "port": 993,
    "mailbox": "INBOX",
    "mark_as_seen": true,
    "email_search": {
        "unseen": true,
        "from": "noreply@vendor.com",
        "subject": "Daily Inventory"
    }
}

S3 (sds3)

The S3 connection type allows your automation to read from or write to Amazon S3 buckets. This is useful when your vendor stages files in S3, or when you use S3 as an intermediate storage layer for large data transfers.

When to Use S3

Files are stored in an Amazon S3 bucket -- either placed there by a vendor, another system, or a separate SureDone process.

Configuration Fields

Complete Example

"connection": {
    "type": "sds3",
    "bucket": "suredone-bulk-staging"
}

SureDone SFTP (sdsftp)

SureDone provides a managed SFTP endpoint for customers. This is useful when a vendor or partner needs to push files directly to a location SureDone can read from, without the customer managing their own SFTP server.

When to Use SureDone SFTP

You want vendors or partners to push files to your SureDone-managed SFTP folder, rather than setting up your own SFTP server.

Configuration Fields

Complete Example

"connection": {
    "type": "sdsftp",
    "path": "/incoming/vendor-inventory",
    "user_id": 12345
}

Common Fields Across Connection Types

A few fields appear across multiple connection types:

Choosing the Right Connection Type