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

# How Notifuse fits together

> The objects Notifuse is built on, from workspaces and contacts to the three ways to send an email, and how they relate.

A Notifuse workspace holds your contacts, the lists they subscribe to and the templates you write. You send to them in one of three ways: a broadcast, a transactional notification or an automation. Every email sent is recorded in the message history, and an email provider you connect does the actual delivery.

## Workspace

A workspace is an isolated tenant. It has its own database, its own integrations, its own members and its own settings.

Use one workspace per product, brand or client. A self-hosted installation can have three without a licence, and each Notifuse Cloud plan includes its own count.

See [Workspaces](https://www.notifuse.com/docs/features/workspaces.md).

## Contacts

A contact is a person you can email. The email address identifies the contact and is the only required field.

A contact can also carry an `external_id`, such as the user ID from your app. It is optional and not unique, so two contacts can share one.

Importing contacts or sending a transactional notification matches contacts by email address: it creates the contact if it doesn't exist yet and updates it if it does.

See [Contacts](https://www.notifuse.com/docs/features/contacts.md).

## Lists and subscription statuses

A list is a group of contacts who subscribed to something, like a newsletter or product updates. A public list appears in the notification center, where contacts can subscribe to it themselves. A private list only takes the contacts the workspace adds. Either kind can require double opt-in, with its own confirmation template.

Each contact has a status in each list it belongs to:

| Status       | What it means                                                                |
| ------------ | ---------------------------------------------------------------------------- |
| Active       | Subscribed. Broadcasts to the list reach this contact.                       |
| Pending      | Waiting for double opt-in confirmation. Not emailed until confirmed.         |
| Unsubscribed | Opted out. Left out of broadcasts unless a broadcast is set to include them. |
| Bounced      | The address bounced. Never emailed.                                          |
| Complained   | The contact marked an email as spam. Never emailed.                          |

In the console, lists live on the **Contacts** page, in its left rail.

See [Lists](https://www.notifuse.com/docs/features/lists.md).

## Segments

A segment is a set of contacts that match rules. Rules combine with AND and OR, and they can look at contact fields, list memberships, activity in the contact's timeline, and custom events and goals.

Segments update in near real time. When something is written to a contact's timeline, Notifuse queues that contact, and a background task recomputes its segments. The task runs every 30 seconds by default.

A rule with a relative date, such as "opened an email in the last 30 days", changes as time passes even when nothing happens to the contact. A separate background task recomputes those segments.

See [Segments](https://www.notifuse.com/docs/features/contacts.md#contact-segmentation-engine).

## Templates

A template is the content of an email: subject, sender and body. The body is MJML with Liquid for personalization, like `{{ contact.first_name }}`. Templates are versioned, and each sent email records the version it used.

You write a template in one of two editors, chosen when you create it and fixed after that:

- **Visual**: drag-and-drop blocks.
- **Code (MJML)**: you write the MJML yourself.

Each template has a category, such as marketing, transactional, welcome or opt-in.

See [Templates](https://www.notifuse.com/docs/features/templates.md).

## Three ways to send

### Broadcasts

A broadcast sends one template to a list, once, now or at a scheduled time.

It needs exactly one list. You can narrow it with segments: the broadcast then goes to list members who are in at least one of the segments, so several segments add up rather than narrow further.

Bounced and complained contacts are always left out, and so are pending contacts of a double opt-in list. Unsubscribed contacts are left out too unless you switch off **Exclude unsubscribed recipients**, for a notice every member must get.

Broadcasts go through the workspace's marketing provider. See [Broadcasts](https://www.notifuse.com/docs/features/broadcast-campaigns.md).

### Transactional notifications

A transactional notification is an email your app triggers for one person: a password reset, an order confirmation, an invitation. You create it in the console under **Transactional**, give it an ID and a template, then send it from your code with `POST /api/transactional.send`.

Each request names a contact. Notifuse creates or updates that contact, then sends.

Transactional notifications go through the workspace's transactional provider. See [Transactional API](https://www.notifuse.com/docs/features/transactional-api.md).

### Automations

An automation is a flow that a contact enters when an event lands on their timeline. Triggers include a contact created or updated, a list subscription or unsubscription, a segment joined or left, an email opened or clicked, and a custom event your app sends.

The flow is made of nodes: delays, emails, branches, filters, A/B tests, webhooks, and adding to or removing from a list. A trigger can fire once per contact or every time the event happens.

Automation emails go through the workspace's marketing provider. See [Automations](https://www.notifuse.com/docs/features/automations.md).

### Which one should I use?

| You want to                                                                           | Use                        |
| ------------------------------------------------------------------------------------- | -------------------------- |
| Send a newsletter or an announcement to a list                                        | Broadcast                  |
| Email one person because of something they did in your app, like resetting a password | Transactional notification |
| Send a sequence that starts on its own, like a welcome series or a win-back email     | Automation                 |

## Message history and Logs

Every email Notifuse sends gets one row in the message history. The row links to what sent it (a broadcast, an automation or a transactional notification), to the list when there is one, and to the template version.

The row also records when the email was delivered, opened and clicked, and whether it bounced, drew a complaint or led to an unsubscribe.

You read the message history under **Logs**, on the **Messages** tab. See [Logs](https://www.notifuse.com/docs/features/logs.md).

## Email providers and their two roles

Notifuse doesn't deliver email itself. Each workspace connects one or more providers: SMTP, Amazon SES, Postmark, Mailgun, SendGrid, SparkPost or Mailjet.

A workspace has two sending roles, and you assign a provider to each:

- **Marketing emails**: broadcasts and automation emails.
- **Transactional emails**: notifications sent through the API, Zapier or Supabase.

One provider can take both roles. A role with no provider sends nothing. Mailjet can only take the transactional role.

You set the roles in **Settings**, under **Integrations**. The [Cloud quickstart](https://www.notifuse.com/docs/quickstart/cloud.md) and the [self-hosted quickstart](https://www.notifuse.com/docs/quickstart/self-hosted.md) walk through it, and each provider has its own page, such as [SMTP](https://www.notifuse.com/docs/integrations/smtp.md) and [Amazon SES](https://www.notifuse.com/docs/integrations/amazon-ses.md).
