---
title: "Create or update contacts"
method: POST
path: "/api/v1/contacts"
tags: ["Contacts"]
---

# Create or update contacts

`POST /api/v1/contacts`

## Request

- Base URL: `https://mailinapp.com`
- URL: `https://mailinapp.com/api/v1/contacts`
- Auth: HTTP bearer

Upserts into one contacts list, keyed by email (case-insensitive): an existing address updates in place, a new one is added. Send one contact (`email` + `fields`) or a batch (`contacts`, at most 500). Every address is verified on the server as it is written; invalid addresses are kept but never sent to. New field names are added to the list's columns (at most 40 per list).

## Request body

- union
  - object
    - `listId` string, required
    - `email` string, email, required
    - `fields` object: Field name → value. Scalars are stored as strings; nested values are ignored.
  - object
    - `listId` string, required
    - `contacts` object[], required
      - `email` string, email, required

## Response `200`

Updated an existing contact (one-contact form), or the batch's counts

- ContactUpsertResult
  - `created` integer, required
  - `updated` integer, required
  - `skipped` integer, required: New contacts not added because the plan's contact limit is reached.
  - `contact` Contact
    - `listId` string, required
    - `listName` string, required
    - `rowId` string, required: Stable per address: the same in every list.
    - `email` string, email, required
    - `fields` object, required
    - `status` 'active' | 'pending', required: pending until a double opt-in signup confirms.
    - `verification` object, nullable, required: The server's email verification verdict; null when not checked yet.
      - `status` 'valid' | 'risky' | 'invalid' | 'unknown', required
      - `reasons` string[], required
      - `checkedAt` integer, required: Epoch ms.
    - `createdAt` integer, required: Epoch ms.
    - `updatedAt` integer, required: Epoch ms.

## Other responses

- `201`: Created a new contact (one-contact form)
- `400`: Invalid request
- `401`: Missing or invalid API key
- `404`: Not found, or not this account's
- `409`: The plan's contact limit is reached (one-contact form)
- `429`: Too many requests for this key

---

[API](https://skmtc.dev/mailinapp/apis/mailinapp-api.md) · [All operations](https://skmtc.dev/mailinapp/apis/mailinapp-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mailinapp/apis/mailinapp-api/revisions/61016f797884?raw)