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

# Projects & Folders

> Organize Lettr email templates into projects and folders by brand, product, or team, and reference a project when sending through the API.

Projects and folders help you organize your email templates. Use projects to separate templates by brand, product, or team, and use folders within projects to group related templates together.

## Overview

The template hierarchy in Lettr works as follows:

```
Team
└── Project (e.g., "Marketing Site")
    ├── Folder (e.g., "Transactional")
    │   ├── Template: welcome-email
    │   ├── Template: password-reset
    │   └── Template: order-confirmation
    └── Folder (e.g., "Newsletters")
        ├── Template: weekly-digest
        └── Template: product-updates
```

Every team has a default project created automatically. Templates are organized into projects and folders, which you can reference when working with the API.

## Using Projects in API Calls

When sending emails with templates, you can specify which project to use:

```javascript theme={null}
await lettr.emails.send({
  from: 'you@example.com',
  to: ['recipient@example.com'],
  subject: 'Welcome',
  template_slug: 'welcome-email',
  project_id: 123
});
```

<Note>
  If you don't specify a `project_id`, Lettr uses the default project for your team.
</Note>

### Listing Templates by Project

When retrieving templates via API, templates are returned with their project context:

```bash theme={null}
curl -X GET "https://app.lettr.com/api/templates" \
  -H "Authorization: Bearer lttr_xxxxxxxxxxxx"
```

Response includes project information:

```json theme={null}
{
  "data": [
    {
      "id": 1,
      "name": "Welcome Email",
      "slug": "welcome-email",
      "project_id": 123,
      "folder_id": 3,
      "created_at": "2026-01-10T09:00:00Z",
      "updated_at": "2026-01-15T14:30:00Z"
    },
    {
      "id": 2,
      "name": "Order Confirmation",
      "slug": "order-confirmation",
      "project_id": 123,
      "folder_id": 5,
      "created_at": "2026-01-12T11:00:00Z",
      "updated_at": "2026-01-20T08:15:00Z"
    }
  ]
}
```

You can scope both endpoints to a specific project by adding `?project_id=123`. If omitted, your team's default project is used.

## Default Project

Every team has a default project. This project:

* Cannot be deleted
* Receives templates when no project is specified
* Is used when API calls don't include a `project_id`

## Best Practices

### Project Organization

* **By Brand**: Create separate projects for each brand if you send emails from multiple brands
* **By Product**: Separate projects for different products or services
* **By Environment**: Consider separate projects for production vs. staging if testing extensively

### Folder Organization

* **By Email Type**: Group transactional, marketing, and notification emails
* **By Customer Journey**: Organize by lifecycle stage (onboarding, engagement, retention)
* **By Frequency**: Separate one-time emails from recurring ones

### Naming Conventions

Use consistent naming patterns:

```
Projects:
- "Acme SaaS"
- "Acme Enterprise"
- "Internal Communications"

Folders:
- "Transactional"
- "Onboarding Sequence"
- "Product Updates"

Templates (slugs):
- welcome-email
- password-reset
- weekly-digest-v2
```

## Related Topics

<CardGroup cols={2}>
  <Card title="Template Editor" icon="paintbrush" href="/learn/templates/topol-editor">
    Create templates with the visual editor
  </Card>

  <Card title="Templates Introduction" icon="file-lines" href="/learn/templates/introduction">
    Get started with email templates
  </Card>

  <Card title="Template Versions" icon="code-branch" href="/learn/templates/versions">
    Manage multiple versions of templates
  </Card>

  <Card title="Storage Domains" icon="hard-drive" href="/learn/domains/storage-domains">
    Configure custom domains for template assets
  </Card>
</CardGroup>