Contact properties

Contact properties store additional information about your contacts that you can then use to personalize your campaigns. Alongside a set of default properties, you can define your own custom properties.

Default properties

Every contact already carries these built-in properties:

• first_name — the contact’s first name.
• last_name — the contact’s last name.
• email — the contact’s email address.
• unsubscribed — whether the contact has unsubscribed from all campaigns.

Custom properties

Create additional custom properties to store whatever you need — a company name, a plan tier, a signup source. Each property has a key, a value, and an optional fallback value.

import { MailBlastr } from 'mailblastr';

const mb = new MailBlastr('mb_xxxxxxxxx');

const { data, error } = await mb.contactProperties.create({
  "key": "company_name",
  "type": "string",
  "fallback_value": "Acme Corp"
});
console.log({ data, error });

Setting a value on a contact

A property’s fallback value is used for any contact that has no explicit value. To set a per-contact value, pass a properties object when you create a contact or update one. You can update a contact by id or by email.

# Set a property while creating a contact
curl -X POST 'https://api.mailblastr.com/contacts' \
  -H 'Authorization: Bearer mb_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "steve@example.com",
    "first_name": "Steve",
    "last_name": "Wozniak",
    "unsubscribed": false,
    "properties": { "company_name": "Acme Corp" }
  }'

# Or update an existing contact by email
curl -X PATCH 'https://api.mailblastr.com/contacts/steve@example.com' \
  -H 'Authorization: Bearer mb_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{ "properties": { "company_name": "Acme Corp" } }'

Validation rules

A property is only applied to a contact if the property key already exists and the supplied value matches the property’s declared type. Otherwise the value is not set and the call fails with an error.

• Unknown key — if the property key does not exist, it is not added and the request fails.
• Wrong type — if the value’s type does not match the property’s type, it is not added and the request fails.
• Case-sensitive keys — company_name, CompanyName, and company_Name are three different keys. Match the key exactly.

Using properties in campaigns

Reference any property — default or custom — in your campaign HTML and text content to personalize each recipient’s message. Properties are resolved per-contact when the campaign is sent, using each contact’s value or the property’s fallback. You can also set this up when you create a campaign via the API.