Managing contacts

A contact is a single person on an audience. Contacts are nested under the audience that owns them — every contact operation runs against /audiences/:audience_id/contacts.

The only required field is email. You can optionally store a first_name and last_name, an unsubscribed flag that controls whether campaigns reach them, and a properties map of custom fields you can use to personalize campaigns.

The contact object

{
  "object": "contact",
  "id": "479e3145-dd0e-4f64-bf48-1d4b6d4cd8f6",
  "email": "steve@example.com",
  "first_name": "Steve",
  "last_name": "Wozniak",
  "unsubscribed": false,
  "properties": {
    "company_name": "Acme Corp"
  },
  "created_at": "2026-06-23T17:30:11.000Z"
}

Emails are stored lowercased. first_name and last_name are null when not provided. properties is always present and includes every registered custom property, merged with fallback values.

Adding a contact

Send the email (required) plus any optional fields to the audience’s contacts collection. Alongside first_name, last_name, and unsubscribed, you can include a properties object of custom field values — each key must already exist as a property on the audience and the value must match its type.

import { MailBlastr } from 'mailblastr';

const mb = new MailBlastr('mb_xxxxxxxxx');

const { data, error } = await mb.contacts.create({
  audienceId: 'AUDIENCE_ID',
  "email": "steve@example.com",
  "first_name": "Steve",
  "last_name": "Wozniak",
  "unsubscribed": false
});
console.log({ data, error });

Upsert by email

Contacts are unique by email within an audience. If you create a contact whose email already exists in that audience, MailBlastr updates the existing contact instead of creating a duplicate — first_name, last_name, and unsubscribed are overwritten with the values you send. This makes the create call safe to call repeatedly (for example, on every signup) without producing duplicates.

Addressing a contact by id or email

Anywhere a contact identifier appears in the path — get, update, delete — you can pass either the contact id or its email. MailBlastr detects which you provided. Both of these refer to the same contact:

GET https://api.mailblastr.com/audiences/AUDIENCE_ID/contacts/479e3145-dd0e-4f64-bf48-1d4b6d4cd8f6
GET https://api.mailblastr.com/audiences/AUDIENCE_ID/contacts/steve@example.com

Contact properties

Every contact has four default properties — email, first_name, last_name, and unsubscribed. You can also define custom properties on an audience to store additional information (for example company_name or plan) and use those values to personalize campaigns.

Set custom values by passing a properties map when you create or update a contact:

{
  "email": "steve@example.com",
  "first_name": "Steve",
  "properties": {
    "company_name": "Acme Corp",
    "plan": "pro"
  }
}

Bulk import by CSV

To add many contacts at once, import a CSV (up to 5 MB / 10,000 contacts per import). Map each CSV column to a contact field — email, first_name, last_name, unsubscribed — or to a custom property. The email column is always required. When a row matches an existing contact by email, the on_conflict setting decides the outcome:

Automatic creation

Next steps

• Create a contact via the API.
• Update a contact — change a name, a property, or the subscribe state.
• Manage unsubscribed contacts.