Managing Contacts via API

Create, read, update, and delete contacts programmatically

Managing Contacts via API

The Contacts API lets you programmatically create, retrieve, update, and delete contacts in your Mailnaptic account. This is the foundation for most integrations — syncing subscribers from your application, importing data from external systems, or building custom signup flows.

Create a contact

Send a POST request to create a new contact. If a contact with the same email already exists, the record is updated (upsert behavior).

POST /api/v1/contacts

{
  "email": "jane@example.com",
  "first_name": "Jane",
  "last_name": "Doe",
  "list_ids": [1, 3],
  "tags": ["website-signup", "trial"],
  "custom_fields": {
    "company": "Acme Inc",
    "plan": "pro"
  }
}

Required fields:

email (string) — must be a valid email address.

Optional fields:

first_name, last_name (string)
list_ids (array of integers) — subscribe the contact to these lists.
tags (array of strings) — attach tags. Tags are created automatically if they don't exist.
custom_fields (object) — key-value pairs matching your organization's custom field slugs.

Get a contact

GET /api/v1/contacts/:id

Returns the full contact record including email, name, status, tags, custom fields, list memberships, and timestamps.

List contacts

GET /api/v1/contacts?page=1&per_page=50

Returns a paginated list of contacts. You can filter by:

Parameter	Type	Description
`status`	string	Filter by status: `active`, `unsubscribed`, `bounced`, `complained`
`list_id`	integer	Only contacts in this list
`tag`	string	Only contacts with this tag
`search`	string	Search by email, first name, or last name

Update a contact

PUT /api/v1/contacts/:id

{
  "first_name": "Janet",
  "custom_fields": {
    "plan": "enterprise"
  },
  "tags": ["enterprise", "upgrade"]
}

Only the fields you include in the request body are updated. Omitted fields are left unchanged. Tags in the request are added to existing tags — they do not replace them.

Delete a contact

DELETE /api/v1/contacts/:id

Permanently removes the contact and all associated data (tag mappings, list memberships, site events, frequency cap records, and consent logs). This is a hard delete for GDPR compliance and cannot be undone.

Manage tags

You can also manage tags independently:

// Add tags
POST /api/v1/contacts/:id/tags
{"tags": ["vip", "high-value"]}

// Remove a tag
DELETE /api/v1/contacts/:id/tags/:tag_name

Manage list memberships

// Subscribe to lists
POST /api/v1/contacts/:id/lists
{"list_ids": [2, 5]}

// Unsubscribe from a list
DELETE /api/v1/contacts/:id/lists/:list_id

Error handling

Common errors when working with the Contacts API:

400 — Invalid email format or missing required fields.
403 — API key lacks contacts:write scope.
404 — Contact ID does not exist.
429 — Rate limit exceeded. Back off and retry.

Batch operations

For importing large numbers of contacts, use the CSV import feature in the Mailnaptic UI or send multiple API requests with reasonable concurrency (5-10 parallel requests). Mailnaptic's upsert behavior ensures no duplicates are created.

Tip: After creating or updating contacts via the API, they are immediately available for segmentation and campaign targeting — no delay or sync required.

Managing Contacts via API