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

POST https://api.mailofly.com/contacts
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

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:

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.

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:

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