---
title: "Marketing: contacts, lists, campaigns and conversions"
description: "This guide covers the marketing features: contacts and their attributes, lists and segments, CSV import, campaigns, A/B tests, reports and conversion tracking."
url: https://onesend.email/docs/marketing/
---
# Marketing: contacts, lists, campaigns and conversions

This guide covers the marketing features: contacts and their attributes, lists and segments, CSV import, campaigns, A/B tests, reports and conversion tracking. Automated journeys (welcome series, abandoned cart, date reminders) are in [Automations](https://onesend.email/docs/automations/). Each section shows the dashboard page and the matching API. All API paths are under `/v1` and need an API key with Full access (`full`) unless noted; read-only calls also accept Read only (`read`) keys. The full schemas are in the API reference at `/docs`.

The examples assume:

```bash
export ONESEND_BASE_URL=http://localhost:3000
export ONESEND_API_KEY=os_live_…
```

Campaign email is sent as type `broadcast` (marketing). It only routes to provider connections with **Use for campaigns** turned on (under **Sending providers**), and it uses your routing policy, quotas and failover like transactional email.

## Transactional or marketing, and sending from your own mailbox

- **A template's type decides how it is sent.** A transactional template is one email to one person (a receipt, a reply): in Compose it is rendered into the message, and the reader's **Reply with template** puts it in your reply. A marketing template is for a list: picking it in Compose opens a new campaign with it.
- **Replies to a campaign can land in your inbox.** Send the campaign from an address on your domain through a provider, with your name as the From name and your inbox's address as **Reply-to**.
- **A campaign through a personal mailbox (Gmail, Outlook) is possible but not advised.** A connected account used for sending is a connection with **Use for campaigns** off; you can turn it on under **Sending providers**. Its daily limit still applies (about 400 a day for Gmail, 250 for Microsoft; the rest waits for the next day), the From address must be on a verified sending domain, and most mailbox providers' terms forbid bulk marketing, so the account can be limited or suspended. Mailbox sending also has no bounce or complaint processing. Use your mailbox for personal mail and replies, and a provider for lists.

## Verify a list before you send

**Contacts → Verify a list** checks addresses before they go on a list: paste them or upload a CSV or text file (up to 5,000 at a time). Each address is checked for its format, whether its domain receives mail (MX), disposable and role addresses (info@, admin@) and your suppression list, 50 at a time through `POST /v1/tools/address`. Nothing is sent to the addresses and no mail server is contacted, so a valid address can still bounce if the mailbox itself does not exist. The result sorts every address into Valid, Risky, Invalid, Suppressed or Unknown with the reason; download the valid ones or all results as CSV, or add the valid ones to contacts (a normal contact import, optionally into a new list). Contact imports also flag typos, domains without a mail server and disposable addresses on their own.

<a id="contacts"></a>
## Contacts

A contact is one email address in your workspace, unique per workspace (stored in lowercase). Each contact has a status:

| Status | Meaning | Receives campaigns |
|---|---|---|
| `subscribed` | Default for new contacts | Yes |
| `unsubscribed` | Unsubscribed by link, by API or in the dashboard | No |
| `bounced` | A hard bounce was recorded | No |
| `complained` | The recipient reported spam | No |
| `inactive` | Stopped opening and did not respond to a re-engagement email ([sunsetting](https://onesend.email/docs/deliverability/#sunsetting)) | Only when the campaign includes inactive contacts |
| `pending` | Signed up through a double opt-in [form](https://onesend.email/docs/forms-and-archive/#double-opt-in) and not confirmed yet | No |

Create or update a contact by email. Attributes are merged, and `null` removes one. `listIds` are added to the contact's existing lists.

```bash
curl -X POST "$ONESEND_BASE_URL/v1/contacts" \
  -H "Authorization: Bearer $ONESEND_API_KEY" -H "Content-Type: application/json" \
  -d '{"email":"ada@example.com","firstName":"Ada","attributes":{"plan":"pro","signup_date":"2026-10-01"},"listIds":["lst_…"]}'
```

Other contact endpoints:

- `GET /contacts` lists contacts. Filter with `q` (email or name), `listId`, `segmentId` and `status` (comma-separated). `nextCursor` is an offset; pass it back unchanged. The response includes `total`.
- `GET /contacts/{id}`, `PATCH /contacts/{id}`, `DELETE /contacts/{id}`.
- `GET /contacts/{id}/activity` returns sends, opens, clicks, bounces, unsubscribes, conversions and list changes for one contact.
- `POST /contacts/bulk` with `ids` and `action`: `add_to_list` or `remove_from_list` (with `listId` or `listIds`), `unsubscribe`, `resubscribe` (only contacts that unsubscribed, never bounced or complained ones), or `delete`.
- `GET /contacts/export` streams a CSV. Filter with `listId`, `segmentId`, `status` or `q`.

<a id="attributes"></a>
### Attributes

Attributes are the fields you store on contacts and use in segments and templates. `email`, `first_name`, `last_name` and `phone` are system attributes and always exist. Create others before you use them, or let a CSV import create them. The contacts API also stores values for keys that are not defined yet, but those values are not exported or offered in the segment builder until you create the attribute.

| Type | Values | Example |
|---|---|---|
| `text` | Any string | `company` |
| `number` | A number | `orders` |
| `date` | ISO 8601 date or time | `signup_date` |
| `boolean` | `true` or `false` | `beta_tester` |
| `category` | One of a fixed set of `options` | `plan` with `free`, `pro`, `team` |

Keys are lowercase letters, digits and underscores, starting with a letter.

```bash
curl -X POST "$ONESEND_BASE_URL/v1/contact-attributes" \
  -H "Authorization: Bearer $ONESEND_API_KEY" -H "Content-Type: application/json" \
  -d '{"key":"plan","label":"Plan","type":"category","options":["free","pro","team"]}'
```

`GET /contact-attributes` lists them. `DELETE /contact-attributes/{key}` removes the definition; values already stored on contacts are kept.

<a id="lists-and-segments"></a>
## Lists and segments

- A **list** is a fixed set of contacts that you add and remove explicitly, for example "Newsletter" or "Beta users". A contact can be in many lists.
- A **segment** is a saved set of conditions. Its members are calculated when you use it, so it updates as contacts change.

Lists: `GET /lists`, `POST /lists` (`name`, optional `description`), `GET /lists/{id}`, `PATCH /lists/{id}` and `DELETE /lists/{id}`. Each list returns `contactCount` and `subscribedCount`. Deleting a list does not delete its contacts.

A segment has `match` (`all` or `any`) and one or more conditions:

| `kind` | Operators | Example |
|---|---|---|
| `attribute` | `eq`, `neq`, `contains`, `not_contains`, `gt`, `lt`, `before`, `after`, `is_set`, `is_not_set` | `{ "kind": "attribute", "key": "plan", "op": "eq", "value": "pro" }` |
| `list` | `in`, `not_in` | `{ "kind": "list", "op": "in", "listId": "lst_…" }` |
| `engagement` | `opened`, `not_opened`, `clicked`, `not_clicked`, with optional `campaignId` and `withinDays` | `{ "kind": "engagement", "op": "opened", "withinDays": 90 }` |
| `status` | `eq`, `neq` | `{ "kind": "status", "op": "eq", "value": "subscribed" }` |

```bash
curl -X POST "$ONESEND_BASE_URL/v1/segments" \
  -H "Authorization: Bearer $ONESEND_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Active pro users","match":"all","conditions":[{"kind":"attribute","key":"plan","op":"eq","value":"pro"},{"kind":"engagement","op":"opened","withinDays":90}]}'
```

`POST /segments/preview` takes the same `match` and `conditions` and returns the number of matching contacts without saving. The other endpoints are `GET /segments`, `GET /segments/{id}`, `PATCH /segments/{id}` and `DELETE /segments/{id}`.

<a id="csv-import"></a>
## CSV import

In the dashboard, open **Contacts** and select **Import contacts**. The API has the same steps: upload, map columns and confirm consent, then poll.

**1. Upload.** Send the file as JSON or as multipart form data with a `file` field. Files can be up to 50 MB and 500,000 rows, UTF-8, with a header row. Comma, semicolon and tab delimiters are detected.

```bash
curl -X POST "$ONESEND_BASE_URL/v1/contacts/imports" \
  -H "Authorization: Bearer $ONESEND_API_KEY" \
  -F "file=@contacts.csv"
```

The response is an import with `status: "uploaded"`, the detected `columns` with sample values, and a `suggested` attribute for each column. Nothing is imported yet.

- `detectedPreset` names the source layout the header matches, if any (see [Source presets](#import-presets)); its column patterns fill in suggestions the generic matching left open.
- Columns that look like a subscription status (`Status`, `Accepts Email Marketing`, …) include `values`, the distinct values with row counts. `statusValues` lists the values of the column suggested as `status`, each with the contact status it would import as.

**2. Map columns, confirm consent and start.**

```bash
curl -X POST "$ONESEND_BASE_URL/v1/contacts/imports/imp_…/start" \
  -H "Authorization: Bearer $ONESEND_API_KEY" -H "Content-Type: application/json" \
  -d '{"mapping":{"Email":"email","First name":"first_name","Plan":"plan","Notes":"ignore"},"newListName":"Imported 2026-11","updateExisting":true,"consentConfirmed":true}'
```

- `mapping` maps each CSV column to an attribute key or `ignore`. Exactly one column must map to `email`. Map a column to `status` to set each contact's status from it (see below); `status` is not stored as an attribute.
- `createMissingAttributes` (default `true`) creates attributes for mapped keys that do not exist yet.
- `listIds` adds the contacts to existing lists; `newListName` creates a list for them.
- `updateExisting` (default `true`) updates contacts that already exist and adds them to the lists. With `false`, rows for existing contacts are skipped entirely: the contacts are not updated and not added to the lists.
- `consentConfirmed` must be `true`. It records that every contact in the file agreed to receive email from you. Do not import purchased or scraped lists.
- `consentConfirmedElsewhere: true` also stores consent proof on each new contact (and on existing contacts that have none): `{ "method": "import", "importId": "imp_…", "submittedAt": "…", "confirmedElsewhere": true }`. Use it when the people in the file subscribed through another system. `consentConfirmed` is still required.
- `preset` records the source preset you used (the mapping itself always comes from `mapping`).
- `statusMapping` sets how values in the `status` column are imported: `{ "<value>": "subscribed" | "unsubscribed" | "bounced" | "complained" | "skip" }` (values are compared case-insensitively). Values not listed use the preset's mapping, then the common values below, then `subscribed`. `skip` leaves the row out; skipped rows are in the error file.
- `fixTypos: true` imports addresses with a likely domain typo (`gmial.com`) with the suggested domain (`gmail.com`) instead.

Contacts already on your suppression list, or with status `bounced`, `complained` or `unsubscribed`, keep that status and are never mailed. A status from the file only ever makes a contact less mailable: it never resubscribes anyone. Rows imported as `unsubscribed`, `bounced` or `complained` are also added to the suppression list, so they apply across every provider.

Common status values, used with any preset or none:

| Values | Imported as |
|---|---|
| empty, `subscribed`, `active`, `confirmed`, `opted in`, `yes`, `true` | `subscribed` |
| `unsubscribed`, `opted out` | `unsubscribed` (suppressed for campaigns) |
| `bounced`, `hard bounce`, `cleaned`, `invalid`, `undeliverable` | `bounced` (suppressed) |
| `complained`, `spam`, `abuse` | `complained` (suppressed) |
| `pending`, `unconfirmed` | left out (`skip`) |

<a id="import-presets"></a>
**Source presets.** In the dashboard, the **Source** choice on the mapping step pre-maps columns for common export layouts. `GET /contacts/import-presets` returns them as data: column-name patterns (compared lowercase, letters and digits only) → attribute keys, and status values → contact status.

| Preset id | Name | Notes |
|---|---|---|
| `newsletter_platform` | Newsletter platform export (email, name, created_at) | `created_at` → `signup_date`; `active`, `free`, `paid` → subscribed |
| `marketing_platform` | Marketing platform export (Email Address, First Name, Last Name, OPTIN_TIME) | `OPTIN_TIME` → `signup_date`; `cleaned` → bounced; `pending`, `transactional`, `archived` → skip |
| `ecommerce_customers` | E-commerce customer export (Email, First Name, Last Name, Accepts Email Marketing) | The marketing consent column is the status: `yes` → subscribed, `no` → skip; `Total Spent` → `total_spent` |
| `plain_list` | Plain list (email, optional name) | Everyone is imported as subscribed |

Imports run in slices: each job run stops after 10 seconds or `importSliceRows` rows (default 20,000) and continues in the next run, so runtimes with a per-invocation query limit (Cloudflare D1 allows 1,000 queries) can lower it.

**3. Poll.** `GET /contacts/imports/{id}` returns `status` (`processing`, then `completed` or `failed`), `processedRows`, and a `result` with `created`, `updated`, `skipped`, `invalid`, the first errors, `statuses` (imported contacts per resulting status) and `quality`: `typos` (with `typosFixed`), `noMx` (domains with no mail server), `disposable`, and up to 50 `samples` with the row, address, finding and suggestion. Mail server lookups are limited per run; addresses not looked up are checked later by the background address check. `GET /contacts/imports/{id}/errors.csv` downloads every row that was not imported, with the reason. `GET /contacts/imports` lists recent imports.

<a id="campaigns"></a>
## Campaigns

In the dashboard, open **Campaigns** and select **Create campaign**.

A campaign has content (a saved template, or `html`), a sender, recipients (lists and segments, minus excluded lists) and tracking settings. Contacts that are unsubscribed, bounced, complained or on the suppression list are skipped automatically.

```bash
curl -X POST "$ONESEND_BASE_URL/v1/campaigns" \
  -H "Authorization: Bearer $ONESEND_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "November product update",
    "subject": "What is new in November",
    "previewText": "Three new features and a pricing change",
    "fromName": "Acme",
    "fromEmail": "news@news.acme.dev",
    "templateId": "tpl_…",
    "recipients": { "listIds": ["lst_…"], "segmentIds": [], "excludeListIds": [] },
    "tracking": { "opens": true, "clicks": true, "utm": { "source": "onesend", "medium": "email", "campaign": "november-update" } },
    "currency": "USD"
  }'
```

The response includes `estimatedRecipients` and `plan`, the number of emails per day and days needed at your current provider quotas.

Templates and `html` can use contact variables: `{{ first_name }}`, `{{ last_name }}`, `{{ email }}`, `{{ phone }}` and any attribute key, also available as `{{ contact.<key> }}`. System variables are `{{ unsubscribe_url }}`, `{{ preferences_url }}`, `{{ view_in_browser_url }}` and `{{ current_year }}`. Campaign email always carries `List-Unsubscribe` and `List-Unsubscribe-Post` headers for one-click unsubscribe (RFC 8058); include `{{ unsubscribe_url }}` in the footer as well.

Each email is rendered for its recipient, including the subject (also when a campaign subject overrides the template's). A variable that no contact field, attribute or system variable provides is empty in every email; template sample data is never sent to real recipients. Create and update requests reject unknown fields with 400.

<a id="campaign-check"></a>
**Check before sending.** `GET /campaigns/{id}/check` returns `ready`, `problems` (what would stop scheduling, the same as the 400 `campaign_incomplete` from `schedule`), `missingVariables` (each `path` with where it is used: `subject`, `preheader` or `content`) and `warnings`. The dashboard shows these in the review step.

<a id="campaign-lifecycle"></a>
### Lifecycle

| Status | How it gets there | What you can do |
|---|---|---|
| `draft` | `POST /campaigns`, or `POST /campaigns/{id}/duplicate` | Edit with `PATCH`, send tests, schedule, delete |
| `scheduled` | `POST /campaigns/{id}/schedule` with a future `scheduledAt` | Schedule again with a new time, pause, cancel |
| `sending` | `schedule` with `scheduledAt: null`, or the scheduled time arrives | Pause, cancel |
| `paused` | `POST /campaigns/{id}/pause`, or a [safeguard](https://onesend.email/docs/deliverability/#automatic-campaign-pause) when bounces or complaints are too high (`pausedReason`) | Resume, cancel |
| `sent` | Every recipient has been handed to a provider | Report |
| `canceled` | `POST /campaigns/{id}/cancel` | Duplicate to send again |
| `failed` | An error stopped sending | Duplicate to send again |

- **Test sends.** `POST /campaigns/{id}/test` with up to 5 addresses in `to` (a Sending only key is enough). Tests go through your routing policy with "[Test]" in the subject and are not counted in the report.
- **Recipients are fixed when sending starts.** Contacts added to a list after that do not receive the campaign.
- **Large audiences.** When the audience is larger than today's remaining quota on providers that allow marketing, the rest is sent on the following days.
- **Pause and cancel** hold or drop emails that have not yet been handed to a provider. Emails already accepted by a provider cannot be recalled.

<a id="ab-testing"></a>
## A/B testing

Test 2 to 4 versions of a campaign on part of the audience, then send the best one to everyone else. In the dashboard, turn on **A/B test** in the campaign editor's **Settings** step; results appear at the top of the report.

```bash
curl -X PATCH "$ONESEND_BASE_URL/v1/campaigns/cmp_…" \
  -H "Authorization: Bearer $ONESEND_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "abTest": {
      "variants": [{ "name": "Plain" }, { "name": "Question", "subject": "Ready for what is new?" }],
      "testPercent": 20, "metric": "click", "durationHours": 4, "winnerSelection": "auto"
    }
  }'
```

- **Variants.** Each variant can change `subject`, `previewText`, `fromName` and the content (`templateId` or `html`). Fields left out use the campaign's own value, so a variant with no changes is the campaign itself. Variants get the ids `a` to `d` in order. Scheduling is refused (`campaign_incomplete`) when the variants are all the same, or one has no subject or content.
- **Test group.** `testPercent` (5 to 50, default 20) of the recipients form the test group, split evenly between the variants; the rest wait (recipient status `held`). Assignment is a stable hash of the campaign and the contact, so it is about, not exactly, the percentage on small audiences.
- **Winner.** `metric` is `open`, `click` or `conversion` rate (per delivered email), or `revenue` per delivered email. After `durationHours` (1 to 168, default 4):
  - `winnerSelection: "auto"` (default): the leading variant is sent to the rest. Ties go to the variant that delivered more.
  - `winnerSelection: "manual"`: the campaign waits (`abTest.phase: "waiting_for_pick"`) until you pick one.
  - `POST /v1/campaigns/{id}/ab-test/winner` with `variantId` sends a variant to the rest now, in either mode (ending an automatic test early).
- **Sending.** The test group goes first, then the rest, through the same plan, warm-up, pacing, quotas and safeguards as any campaign email. The campaign stays `sending` while the rest waits. Pausing holds the decision; resuming after the test period decides at once. Canceling cancels the waiting recipients too. `abTest: null` turns the test off while the campaign is a draft.

`GET /v1/campaigns/{id}/ab-test` (also `abTest` in the campaign report) returns each variant's sent, delivered, opens, clicks, conversions, revenue and rates, the `leader`, and a `summary` in plain words:

| Summary | When |
|---|---|
| "Not enough results yet to compare the variants." | A variant has fewer than 30 delivered emails, or there are fewer than 10 opens, clicks or conversions in total |
| "Variant B is ahead, and the difference is unlikely to be chance (95% confidence)." | The two-proportion z-test between the leader and the runner-up gives p < 0.05 |
| "Variant B is ahead, but the difference may be chance." | p ≥ 0.05 |
| "The variants are performing the same so far." | Equal rates |

`comparison` has the test's `z` and `pValue`. For `revenue`, the test uses the conversion rate. Open rates are inflated by mail apps that load images automatically, so prefer clicks or conversions for close results. A `campaign.ab_winner` webhook event is sent when the winner goes out (`data.campaignId`, `variantId`, `variantName`, `decidedBy`, `remainder`).

<a id="reports"></a>
## Reports and statistics

`GET /campaigns/{id}/report` returns the campaign's counts and rates, an opens, clicks and conversions series (hourly for the first 72 hours, then daily), clicks per link, results by provider and by recipient domain, and bounce reasons. In the dashboard, open the campaign from **Campaigns**.

`GET /campaigns/{id}/recipients` lists per-recipient results. Filter with `filter` (`delivered`, `opened`, `clicked`, `bounced`, `unsubscribed`, `complained`, `converted` or `not_opened`) and `q`. Add `format=csv` to download a CSV.

Rates:

| Rate | Formula |
|---|---|
| Delivery | delivered / sent |
| Open | unique opens / delivered |
| Click | unique clicks / delivered |
| Click-to-open | unique clicks / unique opens |
| Bounce | (hard + soft bounces) / sent |
| Unsubscribe | unsubscribes / delivered |
| Complaint | complaints / delivered |
| Conversion | conversions / delivered |

"Delivered" means accepted by the provider and not bounced. Opens are inflated by Apple Mail Privacy Protection and other clients that load images automatically, so compare open rates over time rather than as absolute numbers.

`GET /statistics/overview` (dashboard: **Statistics**) returns the same rates across all email for a period, compared with the previous period of the same length. Filter by `type` (`transactional` or `marketing`), `campaignId`, `provider`, `domain` (sending domain), `recipientDomain`, `tag` and `templateId`, and group the series by `hour`, `day` or `week`. Daily and weekly buckets start at midnight in the workspace time zone (`timezone` in the response). The range is limited to 31 days for `hour`, 2 years for `day` and 10 years for `week` (400 `range_too_large`).

<a id="conversions"></a>
## Conversions

A conversion credits a purchase, sign-up or other goal to the campaign email that led to it. When click tracking is on, tracked links redirect to your site with an `os_ct` query parameter that identifies the email and recipient.

OneSend attributes a conversion using, in order:

1. `token`: the `os_ct` value from the landing URL.
2. `messageId`: a OneSend message id you stored yourself.
3. `email` (with optional `campaignId`): the most recent campaign click by that address within the attribution window, 7 days by default. Change it with `attributionWindowDays` in the workspace settings (`PATCH /v1/workspace`).

Each request needs at least one of `token`, `messageId` or `email`. When none of them matches an email, the conversion is still recorded, with `attributedBy: "none"`.

### From your server

Use an API key with Full access or Sending only:

```bash
curl -X POST "$ONESEND_BASE_URL/v1/conversions" \
  -H "Authorization: Bearer $ONESEND_API_KEY" -H "Content-Type: application/json" \
  -d '{"token":"<os_ct from the landing URL>","goal":"purchase","value":49,"currency":"USD","idempotencyKey":"order-1001"}'
```

`idempotencyKey` (for example the order id) makes retries safe: the same key records one conversion. `GET /conversions` lists recorded conversions.

### From the browser

Create a key with the **Conversion tracking** permission under **Developers → API keys** (`publishable` in the API). These keys start with `os_pub_` and can only record conversions through `POST /t/conversion`, so they are safe to put in a web page. Every other endpoint rejects them with 403 `publishable_key`.

Add the script to the pages where visitors land and convert:

```html
<script src="https://<your OneSend host>/t/onesend.js" data-key="os_pub_…" async></script>
```

The script reads `os_ct` from the landing URL and keeps it in `localStorage` for 30 days, so the conversion can happen on a later page. Record the conversion when it happens:

```html
<script>
  window.onesend?.convert({ goal: 'purchase', value: 49, currency: 'USD', id: 'order-1001' });
</script>
```

`convert()` accepts `goal`, `value`, `currency`, `id` (used as the idempotency key) and `key` (a Conversion tracking key that overrides `data-key`), and returns a promise with the server response. It attributes only through the `os_ct` token, so it does not accept `email`; to attribute by email address, call `POST /v1/conversions` from your server. If the script has not loaded yet, call `convert()` from the script's `load` event instead.

Conversions and revenue appear in the campaign report and in **Statistics**.

## Compliance

- Import and email only contacts who agreed to receive email from you. The import API requires `consentConfirmed: true`.
- Keep the unsubscribe link in every campaign. Unsubscribes, hard bounces and complaints are added to the suppression list and apply across all providers.
- Send marketing from a separate subdomain (for example `news.acme.dev`) so complaints about campaigns do not affect transactional delivery. See [Domains and DNS](https://onesend.email/docs/domains-and-dns/#one-sending-domain-or-several).
- Follow each provider's terms: many free plans do not allow marketing email. Campaigns route only to connections with **Use for campaigns** turned on under **Sending providers** (`allowBroadcast` in the API).
