Docs / Marketing and deliverability
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. 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:
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.
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) | Only when the campaign includes inactive contacts |
pending | Signed up through a double opt-in form 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.
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 /contactslists contacts. Filter withq(email or name),listId,segmentIdandstatus(comma-separated).nextCursoris an offset; pass it back unchanged. The response includestotal.GET /contacts/{id},PATCH /contacts/{id},DELETE /contacts/{id}.GET /contacts/{id}/activityreturns sends, opens, clicks, bounces, unsubscribes, conversions and list changes for one contact.POST /contacts/bulkwithidsandaction:add_to_listorremove_from_list(withlistIdorlistIds),unsubscribe,resubscribe(only contacts that unsubscribed, never bounced or complained ones), ordelete.GET /contacts/exportstreams a CSV. Filter withlistId,segmentId,statusorq.
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.
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.
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" } |
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}.
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.
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.
detectedPresetnames the source layout the header matches, if any (see Source presets); its column patterns fill in suggestions the generic matching left open.- Columns that look like a subscription status (
Status,Accepts Email Marketing, …) includevalues, the distinct values with row counts.statusValueslists the values of the column suggested asstatus, each with the contact status it would import as.
2. Map columns, confirm consent and start.
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}'
mappingmaps each CSV column to an attribute key orignore. Exactly one column must map toemail. Map a column tostatusto set each contact's status from it (see below);statusis not stored as an attribute.createMissingAttributes(defaulttrue) creates attributes for mapped keys that do not exist yet.listIdsadds the contacts to existing lists;newListNamecreates a list for them.updateExisting(defaulttrue) updates contacts that already exist and adds them to the lists. Withfalse, rows for existing contacts are skipped entirely: the contacts are not updated and not added to the lists.consentConfirmedmust betrue. It records that every contact in the file agreed to receive email from you. Do not import purchased or scraped lists.consentConfirmedElsewhere: truealso 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.consentConfirmedis still required.presetrecords the source preset you used (the mapping itself always comes frommapping).statusMappingsets how values in thestatuscolumn 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, thensubscribed.skipleaves the row out; skipped rows are in the error file.fixTypos: trueimports 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) |
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.
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.
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.
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.
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 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}/testwith up to 5 addresses into(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/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.
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,fromNameand the content (templateIdorhtml). Fields left out use the campaign's own value, so a variant with no changes is the campaign itself. Variants get the idsatodin 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 statusheld). Assignment is a stable hash of the campaign and the contact, so it is about, not exactly, the percentage on small audiences. - Winner.
metricisopen,clickorconversionrate (per delivered email), orrevenueper delivered email. AfterdurationHours(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/winnerwithvariantIdsends 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
sendingwhile the rest waits. Pausing holds the decision; resuming after the test period decides at once. Canceling cancels the waiting recipients too.abTest: nullturns 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).
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).
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:
token: theos_ctvalue from the landing URL.messageId: a OneSend message id you stored yourself.email(with optionalcampaignId): the most recent campaign click by that address within the attribution window, 7 days by default. Change it withattributionWindowDaysin 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:
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:
<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:
<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. - 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 (
allowBroadcastin the API).