Skip to main content

Contact Preferences

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

Recommended: Use Publishable Keys

For contact management operations, we recommend using publishable keys instead of secret API keys. Publishable keys have limited permissions and can safely be used in client-side applications.

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
Using External ID

All preference endpoints support direct access using your external_id - no need to look up the internal contact ID first!

Get Contact Preferences​

Retrieve all preferences for a contact using your external_id:

curl -H "X-API-Key: sk_live_your_api_key" \
     https://api.sendmator.com/api/v1/contacts/external/user_123/preferences

Response:

{
  "preferences": {
    "email": {
      "transactional": true,
      "promotional": false
    },
    "sms": {
      "transactional": true,
      "promotional": true
    },
    "whatsapp": {
      "transactional": true,
      "promotional": false
    },
    "push": {
      "transactional": true,
      "promotional": false
    }
  }
}

Update Preferences​

Update contact preferences using your external_id:

curl -X PATCH https://api.sendmator.com/api/v1/contacts/external/user_123/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": "promotional",
        "subscribed": true
      }
    ]
  }'

Request Body:

FieldTypeRequiredDescription
preferencesarrayYesArray of preference objects to update
preferences[].channelstringYesChannel: email, sms, whatsapp, push
preferences[].categorystringYesCategory: transactional, promotional
preferences[].subscribedbooleanYesWhether the user is subscribed

Response:

Returns the updated contact object.

Preference Categories​

Channels​

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

Categories​

  • transactional: Essential messages like order confirmations, receipts, account updates, security alerts, and OTP codes
  • promotional: Marketing messages like offers, newsletters, campaigns, and announcements

Default Behavior​

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

  • email.promotional: Defaults to false
  • whatsapp.promotional: Defaults to false
  • push.promotional: Defaults to false

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

SDK Examples​

Node.js​

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

// Get preferences by external_id
const prefs = await client.contacts.getPreferencesByExternalId('user_123');

// Update preferences by external_id
await client.contacts.updatePreferencesByExternalId('user_123', {
  preferences: [
    {
      channel: 'email',
      category: 'promotional',
      subscribed: false
    },
    {
      channel: 'sms',
      category: 'promotional',
      subscribed: true
    }
  ]
});