> ## 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.

# Google Sheets

> Automatically import and synchronize contacts from Google Sheets directly into Mailofly segments.

# Google Sheets Audience Sync

Mailofly allows you to connect public Google Sheets directly to your contact segments. New rows added to your spreadsheet are automatically imported as subscribers and contacts in your audience.

This integration lets marketing, sales, and operations teams work in Google Sheets while Mailofly keeps your email segments fresh for campaigns and broadcasts without manual CSV imports.

***

## Why Use Google Sheets Sync?

* **No manual CSV exports**: Stop manually exporting spreadsheets and re-uploading them every time you collect new leads.
* **Flexible header mapping**: Automatically detects `email`, first names, last names, and phone numbers regardless of casing or formatting.
* **Custom contact attributes**: Any extra columns in your sheet (e.g. `company`, `plan`, `source`) are automatically preserved as custom fields for template personalization.
* **Segment isolation**: Connect different tabs or spreadsheets to dedicated segments (e.g. "Webinar Attendees", "VIP Leads", "Beta Waitlist").
* **On-demand and scheduled refresh**: Run instant syncs anytime with one click, or trigger syncs via background schedules and API webhooks.

***

## How It Works

```mermaid theme={null}
flowchart LR
    A[Google Sheet Tab] -->|Public CSV Stream| B[Mailofly Sync Engine]
    B -->|Smart Header Matching| C[Column Parser]
    C -->|Upsert Contact| D[(Mailofly Contacts)]
    D -->|Associate| E[Target Segment]
```

1. **Sheet Fetch**: Mailofly requests the public CSV stream of your specified spreadsheet and sheet tab.
2. **Column Layout Detection**: Mailofly scans row 1 for recognized contact headers.
3. **Contact Upsert**: For each row, the contact is created or updated with name, phone, and custom attributes.
4. **Segment Linking**: Contacts are automatically linked to your chosen audience segment.
5. **Sync Logging**: The connection records the timestamp of the last sync and any column layout errors.

***

## Setup Guide

### 1. Prepare Your Google Sheet

1. Open your Google Sheet in your browser.
2. In the top-right corner, click **Share**.
3. Under **General access**, change the setting to **"Anyone with the link can view"**.
4. Ensure row 1 contains your header titles:
   * **Required**: A column titled `email` (or `Email Address`, `Contact Email`).
   * **Recommended**: Columns like `first_name`, `last_name`, `name`, `phone`.
   * **Custom**: Any other columns you wish to store as custom attributes (e.g. `company`, `role`, `tier`).
5. Note the exact name of the sheet tab at the bottom (e.g. `Sheet1` or `Leads`).

### 2. Connect the Sheet in Mailofly

1. In your Mailofly dashboard, navigate to **[Integrations](https://www.mailofly.com/user/integrations)**.
2. Click on the **Google Sheets** card.
3. Click the **Connect Sheet** button.
4. Complete the connection modal:
   * **Target Segment**: Select an existing segment or click **Create new segment…** to add one on the spot.
   * **Google Sheet URL**: Paste the full shareable URL of your Google Sheet.
   * **Sheet Tab Name**: Enter the exact sheet tab name (default: `Sheet1`).
5. Click **Add connection**.

### 3. Sync Contacts

* Click **Sync now** from the sheet's action menu to import all rows immediately.
* Click **Sync all** in the page header to synchronize all connected sheets across your organization.
* Synced contacts will appear in your **[Contacts](https://www.mailofly.com/user/contacts)** and linked **Segments**.

***

## Column Mapping Reference

Mailofly matches headers flexibly, ignoring case, underscores, hyphens, and whitespace:

| Target Field         | Recognized Sheet Headers                                          |
| -------------------- | ----------------------------------------------------------------- |
| **Email** (Required) | `email`, `email_address`, `e_mail`, `mail`, `contact_email`       |
| **First Name**       | `first_name`, `firstname`, `first`, `fname`, `given_name`         |
| **Last Name**        | `last_name`, `lastname`, `last`, `lname`, `surname`               |
| **Full Name**        | `name`, `full_name`, `fullname`, `display_name`, `contact_name`   |
| **Phone**            | `phone`, `mobile`, `tel`, `telephone`, `phone_number`             |
| **Custom Fields**    | Any other column header (e.g. `company`, `location`, `interests`) |

### Example Spreadsheet Layout

| email                                     | name         | phone        | company     | tier       |
| ----------------------------------------- | ------------ | ------------ | ----------- | ---------- |
| [sarah@acme.com](mailto:sarah@acme.com)   | Sarah Connor | +15551234567 | Cyberdyne   | Enterprise |
| [john@startup.io](mailto:john@startup.io) | John Doe     | +15559876543 | Startup Inc | Pro        |

In this example:

* `email`, `name`, and `phone` map to core contact fields.
* `company` and `tier` are saved as custom fields and can be referenced in emails using `{{custom.company}}` and `{{custom.tier}}`.

***

## Automated Background Sync

To automate regular synchronization (such as daily or hourly cron syncs), trigger the sync webhook endpoint:

```bash theme={null}
curl -X POST https://app.mailofly.com/api/integrations/google-sheets/sync \
  -H "x-google-sheets-sync-secret: YOUR_SYNC_SECRET"
```

This endpoint processes all active Google Sheet connections and updates your segments with newly added rows.

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Error: Sheet CSV is empty or cannot be fetched">
    Verify that your Google Sheet's share permission is set to **"Anyone with the link can view"**. If your Google Workspace domain restricts link sharing outside your organization, adjust your organization's sharing settings.
  </Accordion>

  <Accordion title="Error: Required column 'email' not found">
    Ensure row 1 contains an `email` header. If your sheet has title rows above the headers, adjust your header row or ensure the headers are placed on the very first row.
  </Accordion>

  <Accordion title="Tab not found or wrong data imported">
    Sheet tab names are case-sensitive. Verify that the tab name in Mailofly matches the tab title at the bottom of your Google Sheet exactly (e.g. `Sheet1` vs `sheet1`).
  </Accordion>
</AccordionGroup>


## Related topics

- [Sync Google Sheets to Audience Segments](/guides/tutorials/google-sheets-sync.md)
- [Google workspace](/integrations/google-workspace.md)
- [Integrations](/integrations/index.md)
- [Introduction](/audience/introduction.md)