Actions

The ballerina/ftp package exposes the following clients:

Client	Purpose
`Client`	Connects to FTP/FTPS/SFTP servers for file read/write, directory management, and file operations.

For event-driven integration, see the Trigger Reference.

Client

Connects to FTP/FTPS/SFTP servers for file read/write, directory management, and file operations.

Configuration

Field	Type	Default	Description
`protocol`	`Protocol`	`FTP`	The file transfer protocol to use (`FTP`, `FTPS`, or `SFTP`).
`host`	`string`	`"127.0.0.1"`	Hostname or IP address of the FTP server.
`port`	`int`	`21`	Port number of the FTP server.
`auth`	`AuthConfiguration`	`()`	Authentication configuration including credentials, private key, and secure socket settings.
`userDirIsRoot`	`boolean`	`false`	Whether to treat the user's home directory as the root directory.
`laxDataBinding`	`boolean`	`false`	If true, enables relaxed data binding: null values in JSON/XML map to optional fields, and missing fields map to null values.
`connectTimeout`	`decimal`	`30.0`	Connection timeout in seconds.
`socketConfig`	`SocketConfig`	`()`	Socket timeout configuration for FTP data, FTP socket, and SFTP session timeouts.
`proxy`	`ProxyConfiguration`	`()`	Proxy server configuration for the connection (SFTP only).
`fileTransferMode`	`FileTransferMode`	`BINARY`	File transfer mode (`BINARY` or `ASCII`) (FTP only).
`sftpCompression`	`TransferCompression[]`	`[NO]`	Compression algorithms for SFTP transfers (`ZLIB`, `ZLIBOPENSSH`, or `NO`).
`sftpSshKnownHosts`	`string`	`()`	Path to the SSH known hosts file for SFTP host key verification.
`csvFailSafe`	`FailSafeOptions`	`()`	Fail-safe CSV content processing. When set, malformed CSV records are skipped and written to a separate file in the current directory instead of failing the operation.
`retryConfig`	`RetryConfig`	`()`	Retry configuration for transient failures on non-streaming read operations (getBytes, getText, getJson, getXml, getCsv). If not specified, no retry is attempted.
`circuitBreaker`	`CircuitBreakerConfig`	`()`	Circuit breaker for client operations. When the failure ratio exceeds the configured threshold, the client fails fast without contacting the server until the breaker resets.

Initializing the client

import ballerina/ftp;

configurable string host = ?;
configurable int port = ?;
configurable string username = ?;
configurable string password = ?;

ftp:Client ftpClient = check new ({
    protocol: ftp:FTP,
    host: host,
    port: port,
    auth: {
        credentials: {
            username: username,
            password: password
        }
    }
});

Operations

File reading

getBytes

Retrieves the content of a remote file as a byte array.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The path of the remote file.

Returns: byte[]|Error

Sample code:

byte[] content = check ftpClient->getBytes("/home/user/files/data.bin");

Sample response:

[72, 101, 108, 108, 111]

getText

Retrieves the content of a remote file as a string.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The path of the remote file.

Returns: string|Error

Sample code:

string content = check ftpClient->getText("/home/user/files/readme.txt");

Sample response:

"Hello, this is the content of the file."

getJson

Retrieves the content of a remote file as a JSON value with optional data binding to a record type.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The path of the remote file.
`targetType`	`typedesc<json\|record {}>`	No	The target type for data binding.

Returns: targetType|Error

Sample code:

json data = check ftpClient->getJson("/home/user/files/config.json");

Sample response:

{"name": "App Config", "version": "1.0", "debug": true}

getXml

Retrieves the content of a remote file as an XML value with optional data binding to a record type.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The path of the remote file.
`targetType`	`typedesc<xml\|record {}>`	No	The target type for data binding.

Returns: targetType|Error

Sample code:

xml data = check ftpClient->getXml("/home/user/files/data.xml");

Sample response:

<config><name>App Config</name><version>1.0</version></config>

getCsv

Retrieves the content of a remote CSV file with optional data binding to a record array type.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The path of the remote CSV file.
`targetType`	`typedesc<string[][]\|record {}[]>`	No	The target type for data binding.

Returns: targetType|Error

Sample code:

string[][] data = check ftpClient->getCsv("/home/user/files/report.csv");

Sample response:

[["Name", "Age", "City"], ["Alice", "30", "New York"], ["Bob", "25", "London"]]

getBytesAsStream

Retrieves the content of a remote file as a byte stream, suitable for large files.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The path of the remote file.

Returns: stream<byte[], error?>|Error

Sample code:

stream<byte[], error?> byteStream = check ftpClient->getBytesAsStream("/home/user/files/large-file.zip");

getCsvAsStream

Retrieves the content of a remote CSV file as a stream of rows, suitable for large files.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The path of the remote CSV file.
`targetType`	`typedesc<string[]\|record {}>`	No	The target type for each row.

Returns: stream<targetType, error?>|Error

Sample code:

stream<string[], error?> csvStream = check ftpClient->getCsvAsStream("/home/user/files/large-report.csv");

File writing

putBytes

Writes byte content to a remote file. Supports overwrite and append modes.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The destination file path on the remote server.
`content`	`byte[]`	Yes	The byte content to write.
`option`	`FileWriteOption`	No	Write mode with `OVERWRITE` (default) or `APPEND`.

Returns: Error?

Sample code:

check ftpClient->putBytes("/home/user/files/output.bin", [72, 101, 108, 108, 111]);

putText

Writes string content to a remote file. Supports overwrite and append modes.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The destination file path on the remote server.
`content`	`string`	Yes	The text content to write.
`option`	`FileWriteOption`	No	Write mode with `OVERWRITE` (default) or `APPEND`.

Returns: Error?

Sample code:

check ftpClient->putText("/home/user/files/readme.txt", "Hello, World!");

putJson

Writes JSON content to a remote file. Supports overwrite and append modes.

Note that APPEND performs raw text concatenation, which can produce invalid JSON/XML. Use OVERWRITE unless you specifically intend to concatenate text fragments.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The destination file path on the remote server.
`content`	`json\|record {}`	Yes	The JSON content to write.
`option`	`FileWriteOption`	No	Write mode with `OVERWRITE` (default) or `APPEND`.

Returns: Error?

Sample code:

check ftpClient->putJson("/home/user/files/config.json", {"name": "App", "version": "2.0"});

putXml

Writes XML content to a remote file. Supports overwrite and append modes.

Note that APPEND performs raw text concatenation, which can produce invalid JSON/XML. Use OVERWRITE unless you specifically intend to concatenate text fragments.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The destination file path on the remote server.
`content`	`xml\|record {}`	Yes	The XML content to write.
`option`	`FileWriteOption`	No	Write mode with `OVERWRITE` (default) or `APPEND`.

Returns: Error?

Sample code:

check ftpClient->putXml("/home/user/files/data.xml", xml `<config><name>App</name></config>`);

putCsv

Writes CSV content to a remote file. Supports overwrite and append modes.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The destination file path on the remote server.
`content`	`string[][]\|record {}[]`	Yes	The CSV content as a 2D string array or record array.
`option`	`FileWriteOption`	No	Write mode with `OVERWRITE` (default) or `APPEND`.

Returns: Error?

Sample code:

check ftpClient->putCsv("/home/user/files/report.csv", [
    ["Name", "Age", "City"],
    ["Alice", "30", "New York"],
    ["Bob", "25", "London"]
]);

putBytesAsStream

Writes a byte stream to a remote file, suitable for large files.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The destination file path on the remote server.
`content`	`stream<byte[], error?>`	Yes	The byte stream to write.
`option`	`FileWriteOption`	No	Write mode with `OVERWRITE` (default) or `APPEND`.

Returns: Error?

Sample code:

stream<byte[], error?> byteStream = check ftpClient->getBytesAsStream("/home/user/files/source.dat");
check ftpClient->putBytesAsStream("/home/user/files/destination.dat", byteStream);

putCsvAsStream

Writes a CSV stream to a remote file, suitable for large datasets.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The destination file path on the remote server.
`content`	`stream<string[]\|record {}, error?>`	Yes	The CSV row stream to write.
`option`	`FileWriteOption`	No	Write mode with `OVERWRITE` (default) or `APPEND`.

Returns: Error?

Sample code:

stream<string[], error?> csvStream = check ftpClient->getCsvAsStream("/home/user/files/source.csv");
check ftpClient->putCsvAsStream("/home/user/files/destination.csv", csvStream);

Directory operations

list

Lists the files and directories in the specified remote directory.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The path of the remote directory.

Returns: FileInfo[]|Error

Sample code:

ftp:FileInfo[] files = check ftpClient->list("/home/user/files");

Sample response:

[{"path": "/home/user/files/readme.txt", "size": 1024, "lastModifiedTimestamp": 1711324800000, "name": "readme.txt", "isFolder": false, "isFile": true}, {"path": "/home/user/files/data", "size": 0, "lastModifiedTimestamp": 1711238400000, "name": "data", "isFolder": true, "isFile": false, ...}]

mkdir

Creates a new directory on the remote server.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The path of the directory to create.

Returns: Error?

Sample code:

check ftpClient->mkdir("/home/user/files/new-directory");

rmdir

Removes an empty directory from the remote server.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The path of the directory to remove.

Returns: Error?

Sample code:

check ftpClient->rmdir("/home/user/files/old-directory");

isDirectory

Checks whether the specified remote path is a directory.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The remote path to check.

Returns: boolean|Error

Sample code:

boolean isDir = check ftpClient->isDirectory("/home/user/files/data");

Sample response:

true

File management

rename

Renames a file or directory on the remote server.

Parameters:

Name	Type	Required	Description
`origin`	`string`	Yes	The current path of the file or directory.
`destination`	`string`	Yes	The new path for the file or directory.

Returns: Error?

Sample code:

check ftpClient->rename("/home/user/files/old-name.txt", "/home/user/files/new-name.txt");

move

Moves a file from one location to another on the remote server.

Parameters:

Name	Type	Required	Description
`sourcePath`	`string`	Yes	The current file path.
`destinationPath`	`string`	Yes	The target file path.

Returns: Error?

Sample code:

check ftpClient->move("/home/user/inbox/report.csv", "/home/user/processed/report.csv");

copy

Copies a file from one location to another on the remote server.

Parameters:

Name	Type	Required	Description
`sourcePath`	`string`	Yes	The source file path.
`destinationPath`	`string`	Yes	The destination file path.

Returns: Error?

Sample code:

check ftpClient->copy("/home/user/files/report.csv", "/home/user/backup/report.csv");

delete

Deletes a file from the remote server.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The path of the file to delete.

Returns: Error?

Sample code:

check ftpClient->delete("/home/user/files/old-report.csv");

exists

Checks whether a file or directory exists at the specified remote path.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The remote path to check.

Returns: boolean|Error

Sample code:

boolean fileExists = check ftpClient->exists("/home/user/files/report.csv");

Sample response:

true

size

Retrieves the size of a remote file in bytes.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The path of the remote file.

Returns: int|Error

Sample code:

int fileSize = check ftpClient->size("/home/user/files/report.csv");

Sample response:

Connection management

Closes the connection to the remote FTP/FTPS/SFTP server and releases resources.

Returns: Error?

Sample code:

check ftpClient->close();

Client​

Configuration​

Initializing the client​

Operations​

File reading​

File writing​

Directory operations​

File management​

Connection management​

Client

Configuration

Initializing the client

Operations

File reading

File writing

Directory operations

File management

Connection management