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

# Lists

> Lists in Notifuse are organized collections of contacts that allow you to segment your audience and send targeted email campaigns. They provide the foundation for effective email marketing by enabling precise audience targeting and personalized messaging.

Example:

```
- Newsletter Subscribers
- VIP Customers
- Event Attendees
- Product Updates
```

<img src="https://mintcdn.com/notifuse/Gw4P7NadUImyvZfw/assets/screenshots/lists.png?fit=max&auto=format&n=Gw4P7NadUImyvZfw&q=85&s=495077dc18e7b4bcae9e5955eb1d4135" alt="Mailing lists screenshot" width="2984" height="1874" data-path="assets/screenshots/lists.png" />

## Contact Statuses

Contacts within lists can have different statuses that determine their engagement eligibility:

| Status           | Email Delivery          | Description                                   |
| ---------------- | ----------------------- | --------------------------------------------- |
| **Active**       | ✅ Can receive emails    | Confirmed subscribers eligible for broadcasts |
| **Pending**      | ❌ Cannot receive emails | Waiting for double opt-in confirmation        |
| **Unsubscribed** | ❌ Cannot receive emails | Opted out of receiving communications         |
| **Bounced**      | ❌ Cannot receive emails | Email address is invalid or unreachable       |
| **Complained**   | ❌ Cannot receive emails | Marked emails as spam                         |

> **Important**: Only contacts with **"active"** status can receive emails from broadcast campaigns.

## List Visibility

### Public Lists

* **Notification Center**: ✅ Appear in the notification center
* **Subscriber Access**: Users can see and subscribe to these lists through your notification center
* **Use Case**: Ideal for newsletters, announcements, and general communications

### Private Lists

* **Notification Center**: ❌ Do not appear in the notification center
* **Subscriber Access**: Only accessible through direct management or API
* **Use Case**: Perfect for internal communications, VIP segments, transactional lists, or one-time broadcasts

## Double Opt-In Configuration

### Enabling Double Opt-In

When you activate double opt-in for a list:

* **Imported Contacts**: Contacts added via CSV import or API will always be **"active"** (they bypass double opt-in)
* **Anonymous Subscribers**: Users subscribing via forms (like a newsletter signup on your website) will be **"pending"**
* **Confirmation Required**: Pending contacts must click a confirmation link in their email to become "active"
* **Compliance**: Helps ensure GDPR compliance and reduces spam complaints

**Example**: A visitor fills out a newsletter form on your website → they receive a confirmation email → they click the link (which renders the notification center) → status changes from "pending" to "active"

### Welcome Template (Optional)

* **Purpose**: Automatically sent to contacts when they become "active"
* **Timing**: Triggered after successful subscription or double opt-in confirmation
* **Content**: Welcome message, onboarding information, or subscription confirmation

### Unsubscribe Template (Optional)

* **Purpose**: Automatically sent when contacts unsubscribe from the list
* **Timing**: Triggered immediately when a contact's status changes to "unsubscribed"
* **Content**: Confirmation of unsubscription, feedback request, or alternative communication options

## Re-subscription Handling

When a contact attempts to subscribe to a list they have previously interacted with, Notifuse handles the request based on their current status:

| Current Status   | Behavior                                                                                                       |
| ---------------- | -------------------------------------------------------------------------------------------------------------- |
| **Active**       | No-op. Contact is already subscribed. Returns success silently.                                                |
| **Pending**      | No status change. Re-sends the double opt-in confirmation email.                                               |
| **Unsubscribed** | Allowed. Status is set to **"pending"** and a confirmation email is sent, even if the list uses single opt-in. |
| **Bounced**      | Blocked. Status is not changed and no email is sent.                                                           |
| **Complained**   | Blocked. Status is not changed and no email is sent.                                                           |

### Why bounced and complained contacts are blocked

Re-sending emails to addresses that have previously hard-bounced or filed spam complaints damages sender reputation and can trigger domain blacklisting. These contacts are permanently suppressed at both the application and database level.

### Bulk import behavior

When contacts are imported via CSV or the API with `subscribe_to_lists`, the same protections apply at the database level. Contacts with **unsubscribed**, **bounced**, or **complained** status will not have their list status overwritten. This prevents accidental reactivation of opted-out contacts through bulk operations.

### Privacy by design

Public subscribe endpoints always return HTTP 200 regardless of the contact's internal status. This prevents email enumeration attacks where an attacker could probe the endpoint to determine whether a specific email address is subscribed.

## Best Practices

1. **Status Management**: Regularly review contact statuses to maintain list health
2. **Double Opt-In**: Enable for compliance and to ensure engaged subscribers
3. **Template Setup**: Configure welcome and unsubscribe templates for better user experience
4. **List Organization**: Use separate lists for different audience types (e.g., "Newsletter", "Product Updates") and combine with segment filters for precise targeting in broadcasts