> ## Documentation Index
> Fetch the complete documentation index at: https://ahasend.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> AhaSend stores all message data in the EU. See /facts.
> The API base URL is https://api.ahasend.com. Send the API key in the Authorization: Bearer header. See /api-reference/authentication.
> Use send.ahasend.com for SMTP in the EU, or send-us.ahasend.com as a US connection point forwarding to the EU. Ports 25, 587 and 2525 use STARTTLS. Port 465 is not supported. See /smtp.
> For send-only integrations, create an API Key v2 under Credentials → Add and scope it to messages:send:{your-domain}. See /send-api/credentials and /api-reference/scopes.

# Archive Emails to S3-Compatible Storage

> Archive every AhaSend email (.eml) and delivery log to your own S3, Backblaze B2, DigitalOcean Spaces, Wasabi or MinIO bucket for retention beyond 30 days.

AhaSend S3 archiving copies email messages and delivery logs to S3-compatible storage; this guide covers setup and long-term retention.

Available on Max. See [plans and features](/docs/facts#plans-and-features).

<Tip>
  **Max Plan Feature:** S3 Object Storage archiving is available exclusively to [Max plan subscribers](https://ahasend.com/pricing).
</Tip>

<Info>
  **Extended Compliance:** While AhaSend retains message data for up to 30 days, S3 archiving provides unlimited retention for industries with strict compliance requirements.
</Info>

## Why Use S3 Archiving?

S3-compatible object storage provides a cost-effective solution for long-term email archiving:

<CardGroup cols={2}>
  <Card title="Legal Compliance" icon="scale-balanced">
    Meet regulatory requirements for email retention in finance, healthcare, and legal industries
  </Card>

  <Card title="Cost-Effective Storage" icon="piggy-bank">
    Store unlimited email data at low cost with S3-compatible providers
  </Card>

  <Card title="Complete Control" icon="shield-check">
    Maintain full ownership and control over your archived email data
  </Card>

  <Card title="Easy Retrieval" icon="magnifying-glass">
    Organized directory structure makes finding specific emails simple
  </Card>
</CardGroup>

## Requirements

Before enabling S3 archiving, ensure you meet these prerequisites:

<AccordionGroup>
  <Accordion title="AhaSend Configuration" icon="gear">
    **Message Data Retention Requirements:**

    * Message data retention must be enabled in your AhaSend account
    * Minimum 1-day retention required for AhaSend to process and archive messages
    * Configure retention periods in your [account settings](/docs/retention#account-wide-settings)

    <Note>
      **Why 1-Day Minimum:** AhaSend needs time to process messages and transfer them to your S3 storage before local deletion.
    </Note>
  </Accordion>

  <Accordion title="S3-Compatible Storage" icon="database">
    **Supported Storage Providers:**

    * **Amazon AWS S3** - The original and most feature-complete option
    * **Backblaze B2** - Cost-effective alternative with S3-compatible API
    * **DigitalOcean Spaces** - Developer-friendly with predictable pricing
    * **Wasabi** - S3-compatible object storage
    * **MinIO** - Self-hosted S3-compatible storage solution

    **Required Credentials:**

    * S3 endpoint URL (HTTPS recommended for security)
    * Bucket name (must be pre-created)
    * Access key and secret key with write permission
  </Accordion>
</AccordionGroup>

## Setting Up S3 Archiving

Configure S3 archiving in your AhaSend account settings:

<Steps>
  <Step title="Create S3 Bucket" icon="bucket">
    **Set up your storage bucket:**

    1. **Create a new bucket** in your S3-compatible storage provider
    2. **Configure permissions** to allow write access for your credentials
    3. **Note the bucket name** and endpoint URL for configuration

    <Tip>
      **Bucket Naming:** Use descriptive names like `company-email-archive` or `ahasend-messages-2024` for easy identification.
    </Tip>
  </Step>

  <Step title="Generate Access Credentials" icon="key">
    **Obtain S3 credentials from your provider:**

    * **Access Key ID** - Identifies your account/user
    * **Secret Access Key** - Authenticates API requests
    * **Endpoint URL** - Provider-specific S3 API endpoint

    <Warning>
      **Security:** Use dedicated credentials with minimal permissions (write only).
    </Warning>

    <Info>
      Grant only the object permissions required by your selected S3-compatible provider.
    </Info>
  </Step>

  <Step title="Configure AhaSend" icon="gear">
    **Enable S3 archiving in your AhaSend dashboard:**

    1. **Navigate** to **Account Settings** → **S3 Retention**
    2. **Enter configuration details:**
       * **Endpoint URL:** Your provider's S3 API endpoint (use HTTPS)
       * **Bucket Name:** Name of your pre-created bucket
       * **Access Key:** Your S3 access key ID
       * **Secret Key:** Your S3 secret access key
    3. **Test the connection** to verify configuration
    4. **Save settings** to enable archiving
  </Step>

  <Step title="Verify Setup" icon="check">
    **Confirm archiving is working:**

    1. **Send a test email** through AhaSend
    2. **Wait for asynchronous processing**; this page does not promise an archive completion time
    3. **Check your S3 bucket** for archived files
    4. **Verify file structure** matches expected format
  </Step>
</Steps>

## File Organization Structure

AhaSend organizes archived messages in a logical directory structure for easy navigation and retrieval:

### Directory Pattern

```text theme={null}
RECIPIENT_EMAIL_ADDRESS/YYYY-MM-DD/MESSAGE_ID/MESSAGE_ID.eml
RECIPIENT_EMAIL_ADDRESS/YYYY-MM-DD/MESSAGE_ID/YYYYMMDDTHHMMSSZ-STATUS.txt
```

### Email Address Formatting

Special characters in email addresses are replaced for S3 compatibility:

**Character Replacements:**

* `@` symbol becomes `_AT_`
* `+` symbol becomes `_PLUS_`

**Examples:**

* `john@example.com` becomes `john_AT_example.com`
* `support@mycompany.org` becomes `support_AT_mycompany.org`
* `user+tag@example.com` becomes `user_PLUS_tag_AT_example.com`
* `sales+leads@company.org` becomes `sales_PLUS_leads_AT_company.org`

### Complete Example Structure

```text theme={null}
my-email-archive/
├── john_AT_example.com/
│   ├── 2024-01-15/
│   │   ├── msg_abc123/
│   │   │   └── msg_abc123.eml
│   │   │   └── 20240115T120000Z-Delivery.txt
│   └── 2024-01-16/
│       ├── msg_def456/
│       │   └── msg_def456.eml
│       │   └── 20240116T120000Z-TransientFailure.txt
├── support_AT_mycompany.org/
│   └── 2024-01-15/
│       ├── msg_ghi789/
│       │   └── msg_ghi789.eml
│       │   └── 20240115T120000Z-Bounce.txt
└── user_PLUS_tag_AT_example.com/
    └── 2024-01-15/
        ├── msg_jkl012/
        │   └── msg_jkl012.eml
        │   └── 20240115T120000Z-TransientFailure.txt
        │   └── 20240115T120100Z-Expiration.txt
```

## Archived File Formats

AhaSend saves two types of files for each message:

<AccordionGroup>
  <Accordion title="Message Data (.eml)" icon="envelope">
    **Complete email content in standard EML format:**

    * All email headers (From, To, Subject, Date, etc.)
    * HTML body content
    * Plain text body content
    * All file attachments (base64 encoded)
    * Original message structure preserved

    **Benefits:**

    * Industry-standard format readable by most email clients
    * Contains complete message for legal/audit purposes
    * Can be imported into email clients for viewing
  </Accordion>

  <Accordion title="Delivery Logs (.txt files)" icon="list">
    **Detailed delivery attempt history in text files:**

    * File name: YYYYMMDDTHHMMSSZ-STATUS.txt
    * Content: Raw delivery attempt log from the SMTP server

    **Example content:**

    ```text theme={null}
    The recipient's inbox is out of storage space. Please direct the recipient to  https://support.google.com/mail/?p=OverQuotaTemp 5b1f17b1804b1-46e619a90c2si94549775e9.46 - gsmtp
    ```
  </Accordion>
</AccordionGroup>

## Provider-Specific Configuration

<AccordionGroup>
  <Accordion title="Amazon AWS S3" icon="aws">
    **Configuration:**

    * **Endpoint:** `https://s3.[region].amazonaws.com`
    * **Bucket:** Your S3 bucket name
    * **Credentials:** IAM user with S3 write permissions

    **Example Endpoint URLs:**

    * US East: `https://s3.us-east-1.amazonaws.com`
    * EU West: `https://s3.eu-west-1.amazonaws.com`

    **IAM Policy Example:**

    ```json theme={null}
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": ["s3:PutObject"],
          "Resource": "arn:aws:s3:::your-bucket-name/*"
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Backblaze B2" icon="database">
    **Configuration:**

    * **Endpoint:** `https://s3.[region].backblazeb2.com`
    * **Bucket:** Your B2 bucket name
    * **Credentials:** Application keys with write access

    **Benefits:**

    * Cost-effective storage pricing
    * Check the provider's current storage and transfer terms
    * S3-compatible API
  </Accordion>

  <Accordion title="DigitalOcean Spaces" icon="digital-ocean">
    **Configuration:**

    * **Endpoint:** `https://[region].digitaloceanspaces.com`
    * **Bucket:** Your Spaces name
    * **Credentials:** Spaces access keys

    **Example Endpoints:**

    * New York: `https://nyc3.digitaloceanspaces.com`
    * San Francisco: `https://sfo3.digitaloceanspaces.com`
  </Accordion>
</AccordionGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Storage Management" icon="database">
    **Optimize costs and organization:**

    * Use lifecycle policies to transition older data to cheaper storage tiers
    * Implement bucket versioning for data protection
    * Set up cross-region replication for critical archives
    * Monitor storage usage and costs regularly

    **Example Lifecycle Policy:**

    * Transition to Infrequent Access after 30 days
    * Move to Glacier after 1 year
    * Delete after legal retention period expires
  </Accordion>

  <Accordion title="Security Considerations" icon="shield">
    **Protect your archived data:**

    * Use HTTPS endpoints for all API communications
    * Enable bucket encryption at rest
    * Implement least-privilege access policies
    * Regular audit of access logs and permissions
    * Consider bucket policies to restrict access by IP

    **Access Control:**

    * Create dedicated IAM users/keys for AhaSend integration
    * Rotate access keys periodically
    * Monitor for unauthorized access attempts
  </Accordion>

  <Accordion title="Compliance Strategy" icon="scale-balanced">
    **Meet regulatory requirements:**

    * Document your retention policies and procedures
    * Implement automated deletion based on legal requirements
    * Maintain audit trails of data access and modifications
    * Consider legal hold processes for litigation

    **Retention Planning:**

    * Define retention periods by message type or sender
    * Implement automated cleanup processes
    * Document compliance procedures for auditors
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection Issues" icon="plug">
    **Common configuration problems:**

    * **Invalid endpoint URL:** Verify the correct S3 endpoint for your provider and region
    * **Incorrect credentials:** Double-check access key and secret key
    * **Bucket permissions:** Ensure write access is granted to your credentials
    * **Network connectivity:** Test HTTPS connectivity to the endpoint

    **Testing Connection:**

    ```bash theme={null}
    # Test endpoint connectivity
    curl -I https://your-s3-endpoint.com

    # Verify bucket access with AWS CLI
    aws s3 ls s3://your-bucket-name --endpoint-url=https://your-endpoint
    ```
  </Accordion>

  <Accordion title="Missing Archives" icon="question">
    **Why messages might not be archived:**

    * **Retention disabled:** Message data retention must be enabled
    * **Insufficient retention period:** Minimum 1-day retention required
    * **S3 configuration errors:** Check endpoint, credentials, and bucket name
    * **Processing delays:** Archiving runs asynchronously; files may not appear immediately

    **Verification Steps:**

    1. Check message data retention settings
    2. Verify S3 configuration in account settings
    3. Check the archive bucket and account notifications. If a file is missing, contact support with the message ID; do not send storage credentials
    4. Test with a new email to confirm setup
  </Accordion>

  <Accordion title="File Access Issues" icon="key">
    **Problems accessing archived files:**

    * **Permission errors:** Verify read access to your S3 bucket
    * **File path confusion:** Remember `@` becomes `_AT_` and `+` becomes `_PLUS_` in directory names
    * **Date format:** Ensure you're using YYYY-MM-DD format
    * **Case sensitivity:** S3 object names are case-sensitive

    **File Retrieval Examples:**

    ```bash theme={null}
    # Download specific message (standard email)
    aws s3 cp "s3://your-bucket/john_AT_example.com/<YYYY-MM-DD>/<MESSAGE_ID>/<MESSAGE_ID>.eml" ./

    # Download message with + character in email
    aws s3 cp "s3://your-bucket/user_PLUS_tag_AT_example.com/<YYYY-MM-DD>/<MESSAGE_ID>/<MESSAGE_ID>.eml" ./

    # List all messages for a recipient
    aws s3 ls s3://your-bucket/john_AT_example.com/ --recursive
    ```
  </Accordion>
</AccordionGroup>

## Related Guides

* [API authentication](/docs/api-reference/authentication), [Send-only API keys](/docs/send-api/credentials), [Retention settings](/docs/retention).
* [Account settings API](/docs/api-reference/accounts/update-account), [Message API](/docs/api-reference/messages/get-message), [Plans and limits](/docs/facts).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.