Example: Slack Notifications for New Posts to a Group Email

This walkthrough shows how to forward every email for a shared group address to a Slack channel, as a formatted notification. An example of such an address is team@mail.yourcompany.com.

Overview

Sender → SMTP → Conduit → Webhook endpoint (Slack incoming webhook)

When somebody emails team@mail.yourcompany.com, Conduit receives the message. It then posts a notification to your Slack channel immediately.

Prerequisites

Step 1: Create a Slack incoming webhook

  1. Go to api.slack.com/apps and click Create New App → From scratch.
  2. Name the app, for example "Conduit Email Notifier", and select your workspace.
  3. In Add features and functionality, click Incoming Webhooks. Then turn Activate Incoming Webhooks on.
  4. Click Add New Webhook to Workspace, select the target channel, for example #team-notifications, and click Allow.
  5. Copy the webhook URL. It looks like: 
    https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXX

Step 2: Create the Conduit webhook

Conduit posts the raw email payload to your Slack webhook URL. Slack expects a specific JSON shape ({"text": "..."}), and not the default email payload of Conduit. Use a payload template to convert the message.

Using the web UI

  1. Go to Webhooks (/app/webhooks) and click + New.
  2. Set the address to team@mail.yourcompany.com.
  3. Set the target URL to your Slack incoming webhook URL.
  4. Click Create webhook.
  5. On the webhook detail page, click Edit.
  6. In the Payload template field, enter: 
    {"text": "*New email to team@mail.yourcompany.com*\nFrom: {{.From}}\nSubject: {{.Subject}}\n\n{{.Text}}"}
  7. Click Save changes.

Using the API

POST /api/v1/webhooks
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "address": "team@mail.yourcompany.com",
  "target_url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXX",
  "payload_template": "{\"text\": \"*New email to team@mail.yourcompany.com*\\nFrom: {{.From}}\\nSubject: {{.Subject}}\\n\\n{{.Text}}\"}"
}

Save the secret from the response. You need it if you later add signature verification to a service in the middle.

Payload template explained

The payload_template field is a Go text/template. Conduit renders it against the parsed email. These are the common fields:

Template variable Description
{{.From}} The envelope sender address
{{.Subject}} The subject line of the email
{{.Text}} The plain-text body
{{.HTML}} The HTML body
{{.To}} The list of recipient addresses

For the full list of template variables and the default JSON payload schema, see Webhook Payload Reference.

The rendered output must be valid JSON, and the Slack incoming webhook must accept it.

Step 3: Test the integration

Using the web UI

Open the webhook detail page (/app/webhooks/{id}) and click Simulate. Conduit sends a synthetic payload through the template to your Slack webhook immediately. After a few seconds, a message like this appears in your Slack channel:

New email to team@mail.yourcompany.com From: conduit-simulate@conduit.email Subject: Test delivery from Conduit

This is a simulated test delivery...

Or send a real email

Send an email to team@mail.yourcompany.com from any mail client. The message goes through the full SMTP path, including any attached security policy. After a few seconds, a message like this appears in your Slack channel:

New email to team@mail.yourcompany.com From: alice@example.com Subject: Q3 planning sync

Hi team, let's meet Thursday at 2pm...

Step 4: Review delivery logs

If the Slack notification does not appear, read the delivery log.

Using the web UI

Open Webhooks → team@mail.yourcompany.com → Logs (/app/webhooks/{id}/logs).

Using the API

GET /api/v1/webhooks/wh_01HX.../logs
Authorization: Bearer <access_token>

Common problems:

Error Resolution
http_status: 400 from Slack The payload template is not valid JSON. Test the rendered output against the Slack API.
http_status: 403 from Slack Somebody revoked the Slack webhook URL. Generate a new one in the Slack app settings.
No log entries The email did not reach the SMTP gateway. Examine your MX record, or test with swaks.

Restrict senders with an SMTP security policy

To let only mail from your company domain reach the Slack channel, attach an SMTP security policy. The policy requires a valid DKIM signature from your domain.

Using the web UI

  1. Go to Policies (/app/smtp-policies) and click + New.
  2. Name the policy, for example "company-domain-only". Turn on Require DKIM, and set Allowed DKIM domains to yourcompany.com.
  3. Click Create policy.
  4. Open the Edit form of the webhook (/app/webhooks/{id}/edit), select the new policy in the Security policy list, and click Save.

Using the API

POST /api/v1/smtp-policies
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "name": "company-domain-only",
  "require_dkim": true,
  "allowed_dkim_domains": "yourcompany.com"
}

Then attach it to the webhook:

PUT /api/v1/webhooks/wh_01HX...
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "smtp_security_policy_id": "pol_01HX..."
}

Conduit rejects mail without a valid DKIM signature for yourcompany.com. The rejection happens at the SMTP level, before any delivery to Slack.

For the details, see Configuring an SMTP Security Policy.

Rate-limit the webhook

If the group address receives much traffic, set a rate limit. The limit protects the Slack channel from too many messages.

Using the web UI

Open the Edit form of the webhook (/app/webhooks/{id}/edit), enter a value in the Rate limit field (the maximum emails per minute), and click Save.

Using the API

PUT /api/v1/webhooks/wh_01HX...
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "rate_limit": 10
}

This setting allows a maximum of 10 emails per minute. A sender over the limit gets a 450 transient rejection, and the mail server of that sender retries automatically. No email is lost.