# man > Amazon::S3

---
type: CommandReference
command: Amazon::S3
mode: perldoc
section: 3pm
source: perldoc
---

## Quick Reference
- `$s3 = Amazon::S3->new({aws_access_key_id => $id, aws_secret_access_key => $key})` — Create client
- `$response = $s3->buckets` — List all buckets
- `$bucket = $s3->add_bucket({bucket => 'name'})` — Create a bucket
- `$bucket->add_key('key', 'value', {content_type => 'text/plain'})` — Store a key with metadata
- `$response = $bucket->list` — List keys in a bucket
- `$bucket->delete_key('key')` — Delete a key
- `$bucket->delete_bucket` — Delete an empty bucket

## Name
Amazon::S3 — A portable client library for working with and managing Amazon S3 buckets and keys.

## Synopsis
perl
use Amazon::S3;

my $s3 = Amazon::S3->new({
    aws_access_key_id     => $access_key_id,
    aws_secret_access_key => $secret_access_key,
    retry                 => 1
});

my $bucket = $s3->add_bucket({ bucket => 'my-bucket' });
## Methods
- `new(\%args)` — Creates a new S3 client object. Important arguments:
  - `aws_access_key_id` — AWS Access Key ID
  - `aws_secret_access_key` — AWS Secret Access Key (do not hard‑code in shared code)
  - `secure` — Use HTTPS (0 or 1, default 0)
  - `timeout` — Response timeout in seconds (default 30)
  - `retry` — Enable exponential backoff retries (0 or 1, default 0)
  - `host` — S3 endpoint hostname (default `s3.amazonaws.com`)

- `buckets()` — Returns a hashref with fields:
  - `owner_id` — owner’s ID
  - `owner_display_name` — owner’s display name
  - `buckets` — an arrayref of [Amazon::S3::Bucket](https://metacpan.org/pod/Amazon::S3::Bucket) objects
  Returns `undef` on error.

- `add_bucket(\%args)` — Creates a new bucket.
  Arguments: `bucket` (name), `acl_short` (optional, see ACL documentation).
  Returns 0 on failure, or an [Amazon::S3::Bucket](https://metacpan.org/pod/Amazon::S3::Bucket) object on success.

- `bucket($bucket_name)` — Returns an (unverified) bucket object for the given name. Does not contact the network.

- `delete_bucket($bucket_or_hashref)` — Deletes a bucket. Fails (returns false) if the bucket is not empty. Returns true on success.

- `list_bucket(\%args)` — List keys inside a bucket. Accepts:
  - `bucket` (required) — bucket name
  - `prefix` — filter keys starting with this prefix
  - `delimiter` — group keys by common prefix (CommonPrefixes not yet implemented)
  - `max-keys` — maximum number of results
  - `marker` — pagination marker
  Returns `undef` on error, or a hashref with:
  ```text
  {
      bucket       => $bucket_name,
      prefix       => $prefix,
      marker       => $marker,
      next_marker  => $next_marker,
      max_keys     => $max_keys,
      is_truncated => $is_truncated,
      keys         => [ { key, last_modified, etag, size, storage_class, owner_id, owner_displayname }, ... ]
  }
  
  `next_marker` appears only when a delimiter was used. `is_truncated` indicates more pages exist.

- `list_bucket_all(\%args)` — Convenience wrapper that fetches all keys by handling pagination automatically. Takes the same arguments as `list_bucket`.

## Examples
perl
#!/usr/bin/perl
use warnings;
use strict;
use Amazon::S3;

my $aws_access_key_id     = "Fill me in!";
my $aws_secret_access_key = "Fill me in too!";

my $s3 = Amazon::S3->new(
    {
        aws_access_key_id     => $aws_access_key_id,
        aws_secret_access_key => $aws_secret_access_key,
        retry                 => 1,
    }
);

# List all buckets
my $response = $s3->buckets;

# Create a bucket
my $bucket_name = $aws_access_key_id . '-net-amazon-s3-test';
my $bucket = $s3->add_bucket( { bucket => $bucket_name } )
    or die $s3->err . ": " . $s3->errstr;

# Store a key with content type and custom metadata
my $keyname = 'testing.txt';
my $value   = 'T';
$bucket->add_key(
    $keyname, $value,
    {
        content_type        => 'text/plain',
        'x-amz-meta-colour' => 'orange',
    }
);

# List keys in the bucket
$response = $bucket->list
    or die $s3->err . ": " . $s3->errstr;
print $response->{bucket} . "\n";
for my $key ( @{ $response->{keys} } ) {
    print "\t" . $key->{key} . "\n";
}

# Delete the key
$bucket->delete_key($keyname);

# Delete the bucket
$bucket->delete_bucket;
## See Also
- [Amazon::S3::Bucket](https://metacpan.org/pod/Amazon::S3::Bucket)
- [Net::Amazon::S3](https://metacpan.org/pod/Net::Amazon::S3)
- Amazon S3 service documentation: <http://s3.amazonaws.com/>
- AWS sign‑up: <http://www.amazonaws.com/>