Audience

Everything here belongs to the workspace, like the rest of your data. Contacts are separate from inbox mail and from the transactional Emails API. To email them see Campaigns and Sequences; to pick a subset see Segments.

The contact object#

Add, find and change contacts#

curl -X POST "https://api.runearc.com/v1/contacts?upsert=true" \
  -H "Authorization: Bearer $RUNEARC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "ada@example.com", "first_name": "Ada",
        "tags": ["beta"], "fields": { "plan": "pro" } }'

Without ?upsert=true an address that already exists is refused with contact_exists (409). With it the contact is updated and the answer is 200 instead of 201.

Custom fields#

A custom field has a key (lowercase letters, digits and underscores), a label and a kind: text, number, boolean or date. Values sent in fields are checked against the kind and an unknown key is refused with unknown_field. Use them as variables in email as {{KEY}}; see Email design.

GET/v1/contact-fields

POST/v1/contact-fields

DELETE/v1/contact-fields/{key}

Tags and lists#

Tags are free labels with a name. Lists are named groups with an optional description; a contact can be on many. Deleting a list or a tag never deletes contacts.

Import a CSV#

Upload the file as the raw request body, then start it with a mapping from your columns to contact fields. The header row is required; the delimiter and byte order mark are detected. The upload is stored and previewed first, so nothing is written until you start it.

# 1. Upload the CSV. The answer has the columns, a sample and a suggested mapping.
curl -X POST "https://api.runearc.com/v1/imports?filename=contacts.csv" \
  -H "Authorization: Bearer $RUNEARC_API_KEY" \
  --data-binary @contacts.csv

# 2. Start it with the mapping (202 Accepted; it runs in the background).
curl -X POST https://api.runearc.com/v1/imports/$IMPORT_ID/start \
  -H "Authorization: Bearer $RUNEARC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mapping": { "email": "Email", "first_name": "Name", "fields": { "plan": "Plan" } },
        "tags": ["imported"], "list_ids": [], "update_existing": false }'

# 3. Follow it, then read the rows that failed.
curl https://api.runearc.com/v1/imports/$IMPORT_ID -H "Authorization: Bearer $RUNEARC_API_KEY"
curl "https://api.runearc.com/v1/imports/$IMPORT_ID/errors?format=csv" -H "Authorization: Bearer $RUNEARC_API_KEY"

An import is uploaded, queued, running, done, failed or canceled, and reports total_rows, processed_rows, created_count, updated_count, skipped_count and error_count. Addresses already suppressed are skipped. Up to 25 MB and 500,000 rows per file. GET /v1/imports/{id}/errors lists row_number, email, code and message (up to 10,000 are kept); add ?format=csv for a file you can fix and import again.

Bulk operations#

Tag, add to a list, unsubscribe or delete many contacts in one background job. The selection is a list of ids (at most 5,000), a list of emails (at most 10,000) or a filter with q, status, tag and list_id. Deleting cannot be undone.

curl -X POST https://api.runearc.com/v1/bulk-operations \
  -H "Authorization: Bearer $RUNEARC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": "tag", "tags": ["vip"],
        "selection": { "type": "query", "filter": { "status": "active", "tag": "pro" } } }'

POST /v1/bulk-operations returns 202 and an operation with a status of queued, running, done or failed; poll GET /v1/bulk-operations/{id}. POST /v1/unsubscribes with { "emails": [...] } (at most 10,000) unsubscribes addresses and remembers ones that are not contacts yet.

Unsubscribes and suppression#

Every marketing email carries an unsubscribe link and a one click List-Unsubscribe header; using either sets the contact to unsubscribed. Bounces and complaints set bounced or complained. Marketing sends skip every contact that is not active, and the sender-wide suppression list (hard bounces, complaints, manual blocks) applies to all mail; see Sending. Tracking and the frequency cap are in Tracking.

CLI and MCP#

runearc contacts add ada@example.com --first-name Ada --tag beta
runearc contacts list --status active --tag beta
runearc contacts tag ada@example.com vip
runearc contacts unsubscribe ada@example.com
runearc contacts fields | tags | field-add plan --kind text
runearc lists create Newsletter
runearc lists add lst_... ada@example.com
runearc import start contacts.csv --tag imported --wait
runearc import status | errors <id> --csv
runearc bulk tag vip --status active   # who: --id, --email, --tag, --in-list, --status, --search
runearc bulk list lst_... --email a@example.com   # also: bulk unsubscribe, bulk delete
runearc unsubscribe a@example.com b@example.com
runearc suppressions list | counts | add <address> | remove <address>

MCP tools: add_contact, list_contacts, update_contact, unsubscribe_contact, tag_contacts, create_list, list_lists, add_to_list, import_contacts, get_import, bulk_contacts, unsubscribe_contacts and list_suppressions.

Errors#