Contacts, segments & topics

Contacts are the people you send marketing email to. Segments group contacts for broadcasts and automations. Topics let each contact choose which kinds of email they receive. Contact properties hold your own data, such as a plan or a city, for personalization.

Contacts

A contact is unique by email address within your account. Creating a contact with an email that already exists updates it instead.

curl https://api.jumploon.com/contacts \
  -H "Authorization: Bearer $JUMPLOON_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "email": "ada@example.org",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "properties": { "plan": "pro", "company_size": 40 },
    "segments": ["<segment id>"]
  }'

Field	Description
`email`	Required.
`first_name`, `last_name`	Optional. Available in broadcasts as `FIRST_NAME` and `LAST_NAME`.
`unsubscribed`	`true` stops all broadcasts to this contact.
`properties`	Values for your contact properties.
`segments`	Segment IDs to add the contact to.

You can fetch, update or delete a contact by its ID or its email: GET /contacts/ada@example.org works.

Unsubscribes stay in sync

When a recipient clicks an unsubscribe link, their contact is marked unsubscribed. If you set unsubscribed: false through the API later (for example, after they opt in again), the matching suppression is lifted too.

Segments

curl https://api.jumploon.com/segments \
  -H "Authorization: Bearer $JUMPLOON_API_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "Trial users" }'
 
# Add a contact to it
curl -X POST https://api.jumploon.com/contacts/ada@example.org/segments/<segment id> \
  -H "Authorization: Bearer $JUMPLOON_API_KEY"

GET /segments/:id/contacts lists a segment's members.

Topics

Topics let people unsubscribe from "Product updates" but keep "Billing notices". Each topic has a default:

opt_in: contacts receive it only after they subscribe.
opt_out: contacts receive it unless they unsubscribe.

curl https://api.jumploon.com/topics \
  -H "Authorization: Bearer $JUMPLOON_API_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "Product updates", "description": "New features, about once a month", "default_subscription": "opt_out", "visibility": "public" }'

Set a contact's choices:

curl -X PATCH https://api.jumploon.com/contacts/ada@example.org/topics \
  -H "Authorization: Bearer $JUMPLOON_API_KEY" -H "Content-Type: application/json" \
  -d '{ "topics": [{ "id": "<topic id>", "subscription": "opt_in" }] }'

A broadcast with a topic_id goes only to contacts subscribed to that topic.

Contact properties

Define a property once, then set it on contacts:

curl https://api.jumploon.com/contact-properties \
  -H "Authorization: Bearer $JUMPLOON_API_KEY" -H "Content-Type: application/json" \
  -d '{ "key": "plan", "type": "string", "fallback_value": "free" }'

Field	Description
`key`	Letters, digits and underscores, starting with a letter or underscore, up to 50 characters. Can't be changed later.
`type`	`string` or `number`. Can't be changed later.
`fallback_value`	Used in emails when a contact has no value.

Properties are available in broadcasts as {{{plan}}} and in automation conditions.