Understand schemas, contacts, objects, and events
Learn how contact, object, and event schemas structure your data, which base attributes each type includes, and why schemas matter.
On this page
Start with the message you want to send and the facts it needs. A renewal email goes to a person, refers to their subscription and may follow a plan change. Those are three different parts of your model: a contact, an object and an event.
A schema defines a kind of record and its fields. Customer is a schema; Sarah is one record in it. Order is another schema; each of Sarah's purchases has its own record. Learn the model here, then follow the objects walkthrough to connect a person to an account or purchase history.
The three schema types
maxclicks has exactly three kinds of schema. Each one answers a different question about your business.
- A contact schema describes people you can message.
- An object schema describes any other business entity.
- An event schema describes something that happens.
You can have as many schemas of each type as your business needs. A store might have a Customer contact schema, a Product object schema, and a Purchase completed event schema, all in the same space. The type you choose is permanent, so pick it based on what the records represent.
Contacts are people you can message
A contact schema represents entities that can receive communication, such as Customer, Subscriber, or Student. Contacts are the records you address email to. They carry subscriptions, topics and consent history. Creating a record or putting someone in a segment does not itself grant permission to send; the message still passes eligibility and suppression checks.
Contacts are also the audience for segments and broadcasts. If you need to send email to a kind of record, it must live in a contact schema.
Objects are any other business entity
An object schema represents anything that is not a person you message: a Product, a Company, a Subscription, an Order. Objects hold data and relate to your contacts, but they cannot receive email and carry no consent.
Use an object for something with its own identity, shared facts or several instances per person. Maya and Daniel can belong to one Account object, Studio North. Sarah can have four Order objects without becoming four contacts. A simple personal preference, such as language, can stay as a contact attribute.
An object type is the schema; one account or order is a record of that type. Give each object a stable externalId from your source system so later imports or upserts update the same record. A JSON value on a contact does not create an independent object record.
Connect objects to the right people
For an account relationship, store a custom accountId on Customer and the same source identifier in Account's built-in externalId. Then create an Evaluated attribute on Customer:
Return the Account whose externalId equals this Customer's accountId. Return one account, or no record if there is no match.
Maya and Daniel's accountId can both be studio-north, so their lookups resolve to the same account. That account supplies its plan and name; each contact keeps their own email and preferences. A segment can select the account's admins, and the email can use the account data after you select the relationship in Data.
For commerce, define a many relationship from Customer to Orders, matching the order's customer identifier to the person's userId. Filter the status and specify order and limit, such as the latest three completed orders. Matching names or storing an ID alone does not establish a relationship: review the generated rule and Compute value on a known match and a missing-match record.
Events are things that happen
An event schema represents a time-based occurrence, such as Purchase completed or Cart abandoned. Events are how you drive automation: firing an event can trigger a workflow or an outgoing webhook.
An Order object can change from placed to refunded. Its earlier PurchaseCompleted event remains the purchase occurrence; a RefundIssued event records the later refund. Accepted business occurrences are not edited into new facts, but deleting a subject or schema can erase associated history.
Acceptance and readiness are separate: an event may still be preparing missing AI fields before it becomes available to queries and downstream triggers. Configure and publish the workflow that should respond; receiving an event does not automatically send a message. The events reference covers readiness, collected observations and retry identity.
Base attributes every schema includes
Every schema ships with a fixed set of base attributes. You cannot rename or remove them, because maxclicks and its integrations rely on them being present with the same keys everywhere. They cover the fields almost every business needs, so you rarely start from nothing.
Contact schemas include the richest set, because contacts carry identity and consent.
| Attribute | What it holds |
|---|---|
| The primary email address, used to send and to match contacts. | |
| firstName, lastName | The parts of a person's name. |
| fullName | A single full-name field for when you do not split first and last. |
| phone | A phone number. |
| avatarUrl | A link to a profile image. |
| userId | Your own external identifier for the person, such as an ID from your app. |
| subscriptions | Which channels the contact has consented to. Currently email. |
| topicIds | Which communication topics the contact belongs to. |
| notes | Free-form notes about the contact. |
| tags | Plain labels for grouping and filtering. |
| source | How the contact entered: import, api, form, manual, workflow, or integration. Set by maxclicks. |
| emailStatistics | Per-contact email counts: sent, delivered, bounced, complained, unsubscribed, unique opens, and unique clicks. Set by maxclicks. |
| createdAt, updatedAt | When the contact was created and last changed. Set by maxclicks. |
Because these fields are part of the schema, everything that reads a contact can use them. You can segment on emailStatistics, for example, to find people who have been sent ten emails and opened none.
Object schemas carry a smaller base set. They have their own identity through id and externalId, but do not carry a recipient's email consent.
| Attribute | What it holds |
|---|---|
| externalId | Your identifier for the object from an external system. Unique per schema. |
| notes | Free-form notes about the object. |
| tags | Plain labels for grouping and filtering. |
| createdAt, updatedAt | When the object was created and last changed. Set by maxclicks. |
Event schemas carry the smallest set, because an event is a moment in time with a payload.
| Attribute | What it holds |
|---|---|
| eventId | Your stable occurrence identifier. An identical retry returns the original receipt; different input with the same ID conflicts. |
| occurredAt | When the business action happened. |
| receivedAt, readyAt | When it was accepted, and when preparation completed. |
| contactId or objectId | At most one explicit subject, using its maxclicks record ID. |
| readinessState, definitionRevision | Preparation state and the definition accepted for the occurrence. |
Everything beyond these base attributes is yours to define. You add your own fields, called attributes, on top of the base set. To learn the types available and how to add them, read add attributes to a schema.
Why schemas matter
A schema is more than a label. It does real work every time data enters or is used.
They are a validation gate
When a record enters maxclicks, from an import, a form, the API, a workflow, or an integration, it is checked against its schema first. Fields the schema knows about are stored. Fields it does not know about are dropped.
The API can report omitted keys as warnings. The standard CSV import table shows row results without a per-column warning. Declare fields first, match their keys, and inspect saved values: a successful row does not prove every intended field arrived.
They are the foundation for AI
maxclicks feeds your schema definitions to its AI features. When maxinja writes the logic behind a segment, an evaluated attribute, or a broadcast audience, it reads your schemas and attributes to work out what is possible and to generate logic that runs against your data.
The schema declares the available fields and types. Optional fields can still be empty, so explain what missing data should mean in your audience or email. Clear names and descriptions on your schemas and attributes are what maxinja reads, so vague ones give it less to work from.
Rules that keep schemas safe
A few rules protect you from changes that would break data you already have.
- Type and slug are permanent. Once a schema exists, you cannot change whether it is a contact, object, or event, and you cannot change its slug. The name, plural name, and description are the only fields an update accepts. Choose the type and slug deliberately.
- You always keep at least one contact schema. Once your first contact schema exists, deleting your last one is refused: the space must always have a contact schema to act as the default.
- Deleting a schema deletes its records. Removing a schema permanently removes its records and can remove related data. Cleanup can continue in the background; wait for completion.
- A schema in use cannot be deleted. If attributes, segments, broadcasts, workflow steps, or webhooks reference a schema, maxclicks blocks its deletion until you remove those references.
Where schemas live
You manage schemas in two places. Contact and object schemas live under Settings, then Schemas, where you create them, edit their attributes, and run CSV imports. Event schemas live under Settings, then Events, alongside a viewer for the events that have been fired.
To browse the actual records, open Records in the top bar and choose a schema. That opens its data table, where you filter, search, add records, and run bulk actions. Learn how in add and edit contacts.
If you are setting up your data model for the first time, start with create your first contact schema, then add the fields your business needs with add attributes to a schema.
Did this article answer your question?