​
Default contact properties

These are the default properties for every contact on Cocoonmail. They cannot be deleted.
Contact PropertyDescriptionEmail Tag*API Name**
Emailhi@example.co{email}email
First NameChris{firstName}firstName
Last NameFrantz{lastName}lastName
NotesFavorite color is blue.{notes}N/A
SourceAPI{source}source
SubscribedtrueN/Asubscribed
User GroupInvestors{userGroup}userGroup
User Idask523236{userId}userId
  • Used to add personalization to emails. ** Used in API requests.

​
Source

“Source” describes where the contact originated from. By default, this value will be “Form” for contacts added via a form, or “API” for contacts added via the API. You can specifiy custom “Source” values when adding contacts via forms and the API.

​
Subscribed

The “Subscribed” value determines whether a contact is able to receive Cocoonmail and campaigns. Unsubscribed contacts will receive all transactional emails. Contacts can unsubscribe from your emails using an Unsubscribe link automatically added to your campaigns and Cocoonmail. Some important notes:
  • We do not charge for unsubscribed contacts.
  • We suggest you keep unsubscribed contacts in your audience. If you delete and then re-add them in the future somehow, they may end up being “subscribed” even though they have been unsubscribed.
  • You cannot re-subscribe contacts via a CSV upload or from the Audience page in Cocoonmail. You can re-subscribe contacts with the API and with some of our integrations.

​
User Group

“User Group” is a useful optional property that you can use to segment contacts. It is a free text field that allows you to easily divide contacts into groups like “Users”, “VIPs”, “Investors” or “Customers”. Contacts can currently only have one user group value.

​
User Id

“User Id” is a unique external ID you can assign to each contact in your audience. For example, this could be a customer ID from your store or a user ID from your SaaS. This field is optional but is very useful if you are working with our API. For example, you need a user ID to be able to change a contact’s email address.

​
Custom contact properties

Custom contact properties are additional fields that you can create to store information about contacts.

​
Types of property

Custom contact properties can be one of four different types:
  • String
  • Number
  • Boolean
  • Date (see below) You can specify a property type when creating new properties in Cocoonmail.

​
Dates

When sending dates with the API or via one of our integrations, you can use either a Unix timestamp (in milliseconds) or an ECMA-262 date-time string Timestamps must be in milliseconds and can be sent as either an integer or string. 1705486871000 (if the Unix timestamp is 1705486871) Supported date formats are shown below. These must be sent as a string. Adding a time offset at the end (e.g. +02:00 or -07:00) is optional (if omitted, the date will default to UTC). YYYY-MM-DDTHH:MM:SS.sss YYYY-MM-DDTHH:MM:SS YYYY-MM-DDTHH:MM YYYY-MM-DD HH:MM:SS.sss YYYY-MM-DD HH:MM:SS YYYY-MM-DD HH:MM YYYY-MM-DD

​
Reserved names

Note that Cocoonmail does not allow the creation of properties with the following reserved names: id listId softDeleteAt teamId updatedAt

​
Add a property

One way to create custom contact properties is to go to your Audience and click on any of the column headers, then select Add property. A third way is to go your API Settings page, scroll down to the Contact properties section and click Add property. In each of these cases, you’ll see a form asking you for a property name and type.

​
Deleting contact properties

You can delete properties on the Audience page by clicking on column headers. You can also delete properties from your API Settings page by clicking the trashcan icons. It is not possible to delete default contact properties.
Once a contact property is deleted, all associated data will also be deleted and cannot be recovered. It’s important to be sure that you won’t need the information stored in a property before deleting it.

​
Property in use warning

If you receive a “Property in use” warning modal while deleting a contact property, there are a few things you can check before you’re able to delete the property.
  • If the listed email is a Campaign:
    • Check if the property is in use as dynamic content inside the email editor
    • Ensure this property is not being actively used in the Audience filter
  • If the listed email inside a webflow:
    • Make sure a draft or running webflow is not using it as part of the Audience filter or as a Trigger