Messaging Processor

Configuration reference for email, SMS, and WhatsApp messaging behaviour.

The messaging processor controls how your organization's email, SMS, and WhatsApp messages are dispatched. Each channel (email, SMS, WhatsApp) has its own sub-configuration within the processor.

Endpoint

GET /api/v1/messaging/processor -- Read current configuration.

PUT /api/v1/messaging/processor -- Update configuration.

Scope: messaging:manage

Configuration schema

{
  "config": {
    "email": {
      "enabled": true,
      "preferredProviders": ["provider-a", "provider-b"],
      "fromName": "Your App",
      "replyTo": "support@yourapp.com"
    },
    "sms": {
      "enabled": true,
      "preferredProviders": ["provider-a"],
      "defaultRegionCode": "NG"
    },
    "whatsapp": {
      "enabled": false
    }
  }
}

Email sub-config

Field	Type	Default	Description
enabled	boolean	true	Whether email sending is active
preferredProviders	string[]	Platform default	Provider preference order for failover. PlatformXe selects the first available provider from this list
fromName	string	Organization name	Default sender display name when not specified per-request
replyTo	string	None	Default reply-to address when not specified per-request

SMS sub-config

Field	Type	Default	Description
enabled	boolean	true	Whether SMS sending is active
preferredProviders	string[]	Platform default	Provider preference order for failover
defaultRegionCode	string	"NG"	ISO 3166-1 alpha-2 country code for phone number normalization

WhatsApp sub-config

Field	Type	Default	Description
enabled	boolean	false	Whether WhatsApp messaging is active

How it affects runtime

• Provider failover: When sending an email, PlatformXe tries providers in the order defined by preferredProviders. If the first provider fails, it falls through to the next. This gives you control over cost and reliability trade-offs.
• From name defaults: If a send request omits the fromName field, the processor's configured value is used. Per-request values always override the processor default.
• Region codes: SMS phone numbers without a country prefix are normalized using defaultRegionCode. Set this to the country where most of your recipients are located.

Examples

Set email defaults and enable WhatsApp

curl

curl -X PUT https://api.platformxe.com/api/v1/messaging/processor \
  -H "Content-Type: application/json" \
  -H "x-api-key: pxk_live_your_api_key_here" \
  -d '{
    "config": {
      "email": {
        "fromName": "Acme Notifications",
        "replyTo": "help@acme.com"
      },
      "whatsapp": {
        "enabled": true
      }
    }
  }'

TypeScript SDK

import { PlatformXe } from '@caldera/platformxe-sdk';

const px = new PlatformXe({ apiKey: 'pxk_live_your_api_key_here' });

await px.messaging.updateProcessor({
  config: {
    email: {
      fromName: 'Acme Notifications',
      replyTo: 'help@acme.com',
    },
    whatsapp: { enabled: true },
  },
});

Python SDK

from platformxe import PlatformXe

px = PlatformXe(api_key="pxk_live_your_api_key_here")

px.messaging.update_processor({
    "config": {
        "email": {
            "fromName": "Acme Notifications",
            "replyTo": "help@acme.com"
        },
        "whatsapp": {"enabled": True}
    }
})

Change SMS region code

await px.messaging.updateProcessor({
  config: {
    sms: { defaultRegionCode: 'GH' },
  },
});

Error responses

Code	Description
FORBIDDEN	API key does not have the messaging:manage scope
BAD_REQUEST	Invalid config shape (e.g., unknown provider, invalid region code)
RATE_LIMITED	Rate limit exceeded