Mattermost

Send messages to Mattermost channels using customizable templates. Use Zeotap to notify teams about new leads, audience membership changes, sync completions, or any data-driven events that need human attention in your self-hosted or cloud Mattermost instance.

Prerequisites

A Mattermost instance (self-hosted or Mattermost Cloud)
One of the following:
- A personal access token with permission to post to the target channel
- An incoming webhook configured for the target channel
Personal access tokens must be enabled by a System Admin in System Console > Integrations > Integration Management

Authentication

Mattermost supports two authentication methods:

Personal Access Token

In Mattermost, go to Account Settings > Security > Personal Access Tokens
Click Create Token and give it a descriptive name (e.g., “Zeotap Integration”)
Copy the generated token — it will only be shown once
In Zeotap, select Personal Access Token as the auth method
Paste the token into the Personal Access Token field
Enter your Mattermost Server URL (e.g., https://mattermost.example.com)

Incoming Webhook

In Mattermost, go to Main Menu > Integrations > Incoming Webhooks
Click Add Incoming Webhook
Select the target channel and give the webhook a name
Copy the generated webhook URL
In Zeotap, select Incoming Webhook as the auth method
Paste the URL into the Webhook URL field

Configuration

Mattermost does not require additional configuration fields beyond authentication.

Target Settings

Field	Type	Required	Description
Channel	Text	Conditional	For Personal Access Token auth: the Mattermost channel ID (required). Find it via Channel Menu > View Info. For Incoming Webhook auth: an optional channel name (slug, e.g. `town-square`) to override the webhook’s default channel — channel IDs are not accepted by incoming webhooks.
Message Template	Textarea	Yes	Message template with `{{field_name}}` placeholders that are replaced by row values. Example: `New lead: {{name}} ({{email}})`

Supported Operations

Sync Modes

Mode	Supported
Insert	Yes
Upsert	—
Update	—
Mirror	—

Audience Sync Modes

Mode	Supported
Add	Yes
Remove	—
Mirror	—

Features

Field Mapping: No — message content is controlled by the template
Schema Introspection: No — Mattermost is a messaging destination

How It Works

Zeotap sends a Mattermost message for each row of data:

For each row, the message template is populated by replacing {{field_name}} placeholders with actual row values
The rendered message is sent to the configured Mattermost channel via either:
- The REST API (POST /api/v4/posts) when using Personal Access Token auth
- The incoming webhook endpoint when using Webhook auth
Messages appear in the channel as the authenticated user or the webhook bot

Template Syntax

Use double curly braces to reference row fields:


New lead: {{first_name}} {{last_name}}
Email: {{email}}
Company: {{company_name}}
Score: {{lead_score}}

Any {{field_name}} that does not match a row field is left as-is in the output.

Batch Behavior

Messages are sent individually (one per row) with a ~250ms delay between messages to stay within Mattermost’s rate limits. For large syncs, this means approximately 4 messages per second.

Rate Limits

Mattermost enforces rate limits that vary by deployment configuration. The default rate limit is 10 requests per second per user. Zeotap sends messages at approximately 4 per second to stay well within typical limits.

If the server returns a 429 (Too Many Requests) response, Zeotap respects the Retry-After header and pauses before continuing.

Best Practices

Use descriptive templates: Include enough context in each message so recipients can act without clicking through to another system
Target specific channels: Create dedicated channels for automated notifications to avoid noise in general channels
Use Personal Access Token auth for production integrations — it does not expire (unlike session tokens) and supports channel selection
Use incoming webhooks for simpler setups where you only need to post to a single channel
Monitor sync logs: Check the Zeotap sync history for failed messages and rate-limit warnings

Troubleshooting

Authentication failed

Verify your personal access token has not been revoked. Check that personal access tokens are enabled in System Console > Integrations > Integration Management. Regenerate the token if needed.

Channel not found

Ensure the channel ID is correct. Find the channel ID by clicking the channel name, then View Info — the ID is shown in the dialog. Do not use the channel display name.

Webhook URL invalid

Verify the incoming webhook URL is correct and the webhook has not been deleted. The URL format should be https://your-server.com/hooks/xxxxxxxxxxxxxxxxxxxxx. Recreate the webhook if it was removed.

Messages not appearing

The authenticated user (or webhook bot) must be a member of the target channel. For private channels, manually add the user or bot. For Personal Access Token auth, the user must have create_post permission in the channel.

Rate limited

If you see rate limit errors in the sync logs, your Mattermost instance may have stricter rate limits than the defaults. Contact your Mattermost System Admin to check the rate limit settings in System Console > Environment > Rate Limiting.

SSL/TLS errors

For self-hosted Mattermost instances using self-signed certificates, ensure the certificate is trusted by the Zeotap server. Contact your infrastructure team to add the CA certificate to the trust store.