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

# CSV Campaign

> Upload a spreadsheet where every row is a recipient with their own variable values.

A **CSV campaign** is the best way to send personalised bulk messages when each recipient needs different variable values — order numbers, appointment times, tracking links, etc.

<Note>
  CSV campaigns use the same approved templates as standard campaigns. You're only changing **how recipients and variables are supplied**, not how the message is built.
</Note>

## When to use a CSV campaign

<CardGroup cols={2}>
  <Card title="Order or shipping updates" icon="box">
    Each row has a different order number, tracking link, and delivery date.
  </Card>

  <Card title="Appointment reminders" icon="calendar-check">
    Per-customer time, clinic location, and doctor name.
  </Card>

  <Card title="Exam or event invites" icon="ticket">
    Individual seat numbers, venue details, or QR codes.
  </Card>

  <Card title="One-off imports" icon="file-import">
    Recipients who aren't in your contact list yet but need a single message.
  </Card>
</CardGroup>

## Step 1 — Prepare your CSV

Your CSV must include a column for the **phone number** (with country code) and one column for **each template variable**. Column headers can be any text — you'll map them in the next step.

### Example

For a template body like:

```
Hi {{1}}, your order #{{2}} shipped today. Track it here: {{3}}
```

Your CSV might look like:

```csv theme={null}
phone,firstname,order_id,tracking_url
+14155551234,Alex,A-1001,https://ship.co/t/1001
+14155555678,Priya,A-1002,https://ship.co/t/1002
+442079460958,Sam,A-1003,https://ship.co/t/1003
```

<Warning>
  Every phone number must include the **country code** (`+1`, `+44`, `+91`…). Numbers without it will be rejected.
</Warning>

<Tip>
  Save your CSV as **UTF-8** — especially if your messages contain non-English characters or emojis. In Excel: **Save As → CSV UTF-8**.
</Tip>

## Step 2 — Start a CSV campaign

From the sidebar, go to **Campaigns → CSV Campaign**.

<Steps>
  <Step title="Pick a template">
    Choose an approved template — same as a standard campaign.
  </Step>

  <Step title="Upload your CSV">
    Drag the file onto the drop zone, or click to browse. Xobito parses the file and shows a preview of the first few rows.
  </Step>

  <Step title="Map CSV columns to template variables">
    For each template variable (`{{1}}`, `{{2}}`…) pick the CSV column that supplies its value. The phone-number column is mapped separately.
  </Step>

  <Step title="Confirm the recipient count">
    Xobito shows how many rows were valid, how many were skipped (invalid number, missing required variable, duplicate), and the total estimated cost.
  </Step>

  <Step title="Send or schedule">
    Click **Send Now** to dispatch immediately, or toggle **Schedule** and pick a future time.
  </Step>
</Steps>

<Snippet file="callout-session-window.mdx" />

## Rate limiting and delivery pacing

Xobito automatically paces CSV sends to stay within:

* **Meta's per-second rate limit** for your phone number (varies by tier).
* **Your 24-hour messaging limit** (1K / 10K / 100K / unlimited).

Large CSVs are processed in the background. You can leave the page and come back — the campaign keeps running on Xobito's queue.

<Note>
  Large CSVs typically complete in 20–60 minutes depending on your Meta tier. You'll receive a notification in Xobito when it finishes.
</Note>

## Tracking per-row delivery

Open the campaign details page to see the status of every single row:

| Status        | Meaning                                                                              |
| ------------- | ------------------------------------------------------------------------------------ |
| **Queued**    | Waiting in Xobito's send queue                                                       |
| **Sent**      | Handed off to Meta                                                                   |
| **Delivered** | Reached the recipient's device (single grey tick → double grey)                      |
| **Read**      | Recipient opened the message (double blue tick — only if they have read receipts on) |
| **Failed**    | Rejected by Meta — reason shown per row                                              |

You can **export a CSV of results** with the delivery status of every row — useful for reconciling with your own systems.

## Handling skipped rows

If Xobito skips rows during upload, you'll see a downloadable **errors.csv** with the original row plus an error message. Common reasons:

<AccordionGroup>
  <Accordion title="Invalid phone number">
    Missing country code, letters in the number, or fewer digits than required. Fix the row and re-upload just the corrected rows as a new campaign.
  </Accordion>

  <Accordion title="Missing required variable">
    A template variable column is blank for this row. Either fill it in, or remove the row.
  </Accordion>

  <Accordion title="Duplicate phone number">
    The same number appears more than once. Xobito keeps the first occurrence and flags the rest.
  </Accordion>

  <Accordion title="Contact is opted out">
    The recipient previously unsubscribed. They cannot be re-messaged until they opt back in by sending you a new message.
  </Accordion>
</AccordionGroup>

## Tips for large CSVs

<Check>As a practical guideline, keep CSVs under **\~10 MB and \~50,000 rows** so the browser parses the preview quickly. Larger files still work — they just take longer to validate up front.</Check>
<Check>Validate phone numbers in Excel or Google Sheets before uploading.</Check>
<Check>Test with a 2–3 row file first to verify the mapping is correct.</Check>
<Check>Schedule large CSVs for off-peak hours to keep your inbox manageable.</Check>

## Next

<CardGroup cols={2}>
  <Card title="Schedule a campaign" icon="clock" href="/campaigns/schedule-campaign">
    Queue your CSV send for a specific date and time.
  </Card>

  <Card title="Track performance" icon="chart-line" href="/campaigns/track-performance">
    See delivery, read, and failure stats.
  </Card>
</CardGroup>