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

# Contacts

# Contacts & segments

**Contacts** are people you may email. **Segments** are saved audiences you attach to campaigns — keeping blast scope explicit and auditable.

**In the app:** [Contacts](https://www.mailofly.com/user/contacts)

***

## Contacts

Each contact belongs to your organization and has:

| Field                             | Required | Notes                                        |
| --------------------------------- | -------- | -------------------------------------------- |
| `email`                           | ✓        | Unique per workspace                         |
| `first_name`, `last_name`, `name` |          | Used in merge tags                           |
| `phone`                           |          | Optional                                     |
| `custom_fields`                   |          | JSON key/value for `{{ custom.field }}` tags |
| `status`                          |          | `subscribed` or `unsubscribed`               |

### Add contacts

**Manual:** Contacts tab → Add contact → fill fields → Save.

**CSV import:** Segments tab → select segment → Import CSV.

Supported CSV headers (case-insensitive):

```
email, first_name, last_name, name, phone, status
```

Any additional columns map to `custom_fields` automatically.

***

## Segments

A segment is a named list of contacts. Campaigns always target **one segment** — you always know exactly who received a send.

### Create a segment

1. **Contacts → Segments tab → New segment**
2. Name it (e.g. "Newsletter", "Beta testers")
3. Import CSV or add contacts manually
4. Attach the segment when creating a campaign

### Many-to-many membership

One contact can belong to multiple segments. Updating a contact's email or fields reflects everywhere they're used.

***

## Google Sheets sync

Keep a segment in sync with a published Google Sheet — new rows become contacts automatically.

<Warning>
  Google Sheets sync requires a **Basic plan or higher**.
</Warning>

### Connect a sheet

1. **Contacts → Google Sheet tab**
2. Select target **segment**
3. Paste the **sheet URL** (must be publicly readable or published)
4. Set **sheet name** (tab) and **header row** (usually row 1)
5. Click **Sync**

### Column mapping

Mailofly maps headers by alias:

| Recognized headers                      | Maps to                       |
| --------------------------------------- | ----------------------------- |
| `email`, `e-mail`, `mail`               | `email`                       |
| `first_name`, `firstname`, `given name` | `first_name`                  |
| `last_name`, `lastname`, `surname`      | `last_name`                   |
| `company`, `organization`               | `custom_fields.company`       |
| Unrecognized columns                    | `custom_fields.{column_name}` |

Sync is incremental — only new rows since the last sync are imported.

***

## Subscription status

Mark contacts `unsubscribed` to record opt-out preference. Manage bulk status from the Contacts table or CSV import.

<Info>
  Always honor unsubscribe requests. Mailofly tracks status for your records — combine with your own compliance policies.
</Info>

***

## API

```bash theme={null}
# List contacts
curl -sS "https://api.mailofly.com/v1/contacts?page=1&page_size=50" \
  -H "Authorization: Bearer mf_live_…"

# Create a segment
curl -sS -X POST "https://api.mailofly.com/v1/segments" \
  -H "Authorization: Bearer mf_live_…" \
  -H "Content-Type: application/json" \
  -d '{"name": "Newsletter"}'
```

See [API: Contacts](https://docs.mailofly.com/api/contacts) and [API: Segments](https://docs.mailofly.com/api/segments).

***

## Related

* [Templates](templates.md) — personalize with contact fields
* [Campaigns](campaigns.md) — attach a segment to a send
* [Integrations → Google Workspace](https://docs.mailofly.com/integrations/google-workspace)


## Related topics

- [Topics](/audience/topics.md)
- [Index](/changelog/index.md)
- [Contacts](/audience/contacts.md)
- [Introduction](/broadcasts/introduction.md)
- [Create Contact](/api/contacts/create-contact.md)