> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Contacts

> Add people to your audience, update their info, and keep your list clean.

# Contacts 🙋

A Contact is a person in your audience. You store their email, maybe their name, and any extra info that's useful to you. Then you can use that info to send them personalized emails or add them to automations.

***

## What does a Contact look like?

| Field | Type | What it is |
| :- | :- | :- |
| `id` | string | A unique ID for this contact (starts with `cnt_`) |
| `email` | string | Their email address. Must be unique in your org. |
| `first_name` | string | Their first name (optional) |
| `last_name` | string | Their last name (optional) |
| `unsubscribed` | boolean | If `true`, they've opted out of marketing. Don't send campaigns to them. |
| `properties` | object | Any extra info you want to store — plan, company, anything |
| `created_at` | string | When they were added |

***

## Adding a contact via the API

```http theme={null}
POST https://api.mailofly.com/contacts
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

```typescript theme={null}
import { Mailofly } from "@mailofly/node";

const mailofly = new Mailofly("mfly_live_your_api_key");

const { data, error } = await mailofly.contacts.create({
  email: "sarah@example.com",
  first_name: "Sarah",
  last_name: "Connor",
  properties: {
    plan: "pro",
    company: "Acme Corp",
    mrr: 299,
  },
});

console.log("Contact added:", data.id);
```

***

## Updating a contact

You can update any field on a contact at any time — useful when someone upgrades their plan or changes their name:

```typescript theme={null}
await mailofly.contacts.update("cnt_abc123", {
  properties: {
    plan: "enterprise",
    mrr: 999,
  },
});
```

***

## Deleting a contact

Deleting permanently removes the contact and all their stored data.

**One important thing:** if they previously unsubscribed, their email stays on the global suppression list even after deletion. This protects you — if they come back as a new contact, they won't accidentally get marketing emails they opted out of.

```typescript theme={null}
await mailofly.contacts.delete("cnt_abc123");
```

***

## Tip: Upsert instead of create

If you're not sure whether a contact already exists, you can use `upsert` — it'll update if they exist, or create them if they don't:

```typescript theme={null}
await mailofly.contacts.upsert({
  email: "sarah@example.com",
  first_name: "Sarah",
  properties: { plan: "pro" },
});
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.