Contact Preferences

Manage communication preferences for contacts across different channels and message categories.

Overview

Contact preferences allow users to control which types of messages they receive on different channels. Each preference is a combination of:

• Channel: email, sms, whatsapp, push
• Category: transactional, promotional, utility, conversational, marketing, service, system

info

Preferences use the contact's internal id, not external_id. If you only have the external_id, first call GET /api/v1/contacts/external/{external_id} to get the contact object.

Get Contact Preferences

Retrieve all preferences for a contact with defaults for unset values.

Endpoint

GET /api/v1/contacts/{id}/preferences

Headers

X-API-Key: sk_live_your_api_key

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Contact ID (internal UUID)

Example Request

# If you have the contact's internal ID
curl -H "X-API-Key: sk_live_your_api_key" \
     https://api.sendmator.com/api/v1/contacts/123e4567-e89b-12d3-a456-426614174000/preferences

# If you only have external_id, first get the contact
curl -H "X-API-Key: sk_live_your_api_key" \
     https://api.sendmator.com/api/v1/contacts/external/user_123

Example Response

{
  "preferences": {
    "email": {
      "transactional": true,
      "promotional": false,
      "utility": true,
      "conversational": true,
      "marketing": false,
      "service": true,
      "system": true
    },
    "sms": {
      "transactional": true,
      "promotional": true,
      "utility": true,
      "conversational": true,
      "marketing": true,
      "service": true,
      "system": true
    },
    "whatsapp": {
      "transactional": true,
      "promotional": true,
      "utility": true,
      "conversational": false,
      "marketing": false,
      "service": true,
      "system": true
    },
    "push": {
      "transactional": true,
      "promotional": false,
      "utility": true,
      "conversational": true,
      "marketing": false,
      "service": true,
      "system": true
    }
  },
  "totalPreferences": 28,
  "subscribedCount": 25,
  "unsubscribedCount": 3,
  "subscriptionRate": 89.29
}

Update Multiple Preferences

Batch update channel and category preferences. Only updates specified preferences, leaving others unchanged.

Endpoint

PATCH /api/v1/contacts/{id}/preferences

Headers

X-API-Key: sk_live_your_api_key
Content-Type: application/json

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Contact ID (internal UUID)

Request Body

Field	Type	Required	Description
preferences	array	Yes	Array of preference objects to update
preferences[].channel	string	Yes	Channel: email, sms, whatsapp, push
preferences[].category	string	Yes	Category: transactional, promotional, utility, conversational, marketing, service, system
preferences[].subscribed	boolean	Yes	Whether the user is subscribed to this preference

Example Request

curl -X PATCH https://api.sendmator.com/api/v1/contacts/123e4567-e89b-12d3-a456-426614174000/preferences \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "preferences": [
      {
        "channel": "email",
        "category": "promotional",
        "subscribed": false
      },
      {
        "channel": "sms",
        "category": "marketing",
        "subscribed": true
      },
      {
        "channel": "whatsapp",
        "category": "conversational",
        "subscribed": false
      }
    ]
  }'

Example Response

Returns the updated contact object (same as GET /api/v1/contacts/{id}).

Update Single Preference

Update a specific channel + category preference for a contact.

Endpoint

PATCH /api/v1/contacts/{id}/preferences/{channel}/{category}

Headers

X-API-Key: sk_live_your_api_key
Content-Type: application/json

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Contact ID (internal UUID)
channel	string	Yes	Channel: email, sms, whatsapp, push
category	string	Yes	Category: transactional, promotional, utility, conversational, marketing, service, system

Request Body

Field	Type	Required	Description
subscribed	boolean	Yes	Whether the user is subscribed to this preference

Example Request

curl -X PATCH https://api.sendmator.com/api/v1/contacts/123e4567-e89b-12d3-a456-426614174000/preferences/email/promotional \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "subscribed": false
  }'

Example Response

Returns the updated contact object (same as GET /api/v1/contacts/{id}).

Using External ID

If you manage contacts using your own external_id, you need to first fetch the contact to get the internal id:

# Step 1: Get contact by external_id
CONTACT=$(curl -H "X-API-Key: sk_live_your_api_key" \
     https://api.sendmator.com/api/v1/contacts/external/user_123)

# Step 2: Extract the id from response
CONTACT_ID=$(echo $CONTACT | jq -r '.id')

# Step 3: Get or update preferences using the internal id
curl -H "X-API-Key: sk_live_your_api_key" \
     https://api.sendmator.com/api/v1/contacts/$CONTACT_ID/preferences

Preference Categories

Channel Types

• email: Email messages
• sms: SMS text messages
• whatsapp: WhatsApp messages
• push: Push notifications

Message Categories

• transactional: Order confirmations, receipts, account notifications
• promotional: Sales, offers, discounts
• utility: Password resets, verification codes, service updates
• conversational: Two-way conversations, support chats
• marketing: Newsletters, product updates, announcements
• service: Service-related notifications, maintenance alerts
• system: Critical system messages, security alerts

Default Behavior

When a contact is created, all preferences default to true (subscribed) except:

• email.promotional: Defaults to false
• email.marketing: Defaults to false

This ensures users receive important transactional and utility messages by default, while requiring explicit opt-in for marketing communications.

Best Practices

1. Use External ID: Store your own user IDs as external_id when creating contacts for easy lookup
2. Respect Preferences: Always check contact preferences before sending messages
3. Provide Preference Center: Give users a way to manage their own preferences (see Preference Center API)
4. Handle Unsubscribes: When a user unsubscribes from promotional emails, update their preferences accordingly
5. Granular Control: Use channel + category combinations for fine-grained control over message types

SDK Examples

Node.js

const sendmator = require('@sendmator/sdk');
const client = sendmator.init({ apiKey: 'sk_live_your_api_key' });

// Get contact by external_id
const contact = await client.contacts.getByExternalId('user_123');

// Get preferences
const prefs = await client.contacts.getPreferences(contact.id);

// Update multiple preferences
await client.contacts.updatePreferences(contact.id, {
  preferences: [
    {
      channel: 'email',
      category: 'promotional',
      subscribed: false
    },
    {
      channel: 'sms',
      category: 'marketing',
      subscribed: true
    }
  ]
});

// Update single preference
await client.contacts.updateSinglePreference(
  contact.id,
  'email',
  'promotional',
  false
);

Related Endpoints

• Get Contact by External ID
• Add Contact
• Update Contact
• Preference Center