Audience & broadcasts

Contact properties

Declare custom fields for your contacts, store values on each contact, and use them as variables with fallbacks in broadcasts.

Contact properties are custom fields such as company or plan. You declare each property once for the project, then store a value for it on each contact. In a broadcast, a property is available as a variable, so you can personalize every email.

Declare a property

A contact can only hold a property that has been declared. Storing an unknown key returns 422 validation_error: "Unknown contact property company. Create it first."

In the dashboard, open Audience and choose Properties. With the API, use a full_access key:

Shell

curl -X POST https://api.sooner.dev/contact-properties \
  -H "Authorization: Bearer $SOONER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "key": "company", "type": "string", "fallback_value": "your team" }'

JSON

{ "object": "contact_property", "id": "jp8c3v6x9z2m5n1b4q7w0e3r" }

Field	Type	Required	Description
`key`	string	Yes	Letters, digits and underscore, 1 to 50 characters. Must be unique in the project.
`type`	string	Yes	`string` or `number`. You cannot change it later.
`fallback_value`	string, number or null	No	Used in broadcasts when a contact has no value. Must match `type`.

Store values on contacts

Set values with properties when you create or update a contact:

Shell

curl -X PATCH https://api.sooner.dev/contacts/ada@example.com \
  -H "Authorization: Bearer $SOONER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "properties": { "company": "Acme", "seats": 12 } }'

A value must match the property's type, or be null to clear it. Updates merge into the existing values.

Use properties in a broadcast

Reference a property by its key with the same triple-brace syntax as templates:

html

<p>Hi {{{FIRST_NAME|there}}},</p>
<p>Here is what is new for {{{company}}}.</p>

For each recipient, Sooner fills the variable with the contact's value. If the contact has no value, it uses the property's fallback_value, then an inline fallback such as {{{company|your team}}}, and otherwise an empty string. Keys are matched without regard to case.

Four variables are built in and always available: FIRST_NAME, LAST_NAME, EMAIL and RESEND_UNSUBSCRIBE_URL. Do not declare a property with one of these names, because the built-in value takes priority. See Broadcasts.

Update a fallback

PATCH /contact-properties/{id} changes the fallback_value. It is the only field you can change. To use a different key or type, create a new property.

Shell

curl -X PATCH https://api.sooner.dev/contact-properties/jp8c3v6x9z2m5n1b4q7w0e3r \
  -H "Authorization: Bearer $SOONER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "fallback_value": "there" }'

Delete a property

DELETE /contact-properties/{id} deletes the property declaration. You can no longer store that key on contacts. In the dashboard, deleting a property needs the admin role.

See the contact properties API reference for every endpoint.