Build a custom provider for Courier

Prerequisites

An HTTPS endpoint you control, ready to receive Courier’s webhook
The authentication your endpoint expects, if any

Setup

Open the . Enter your webhook HTTP address and choose an authentication model.

You can now add the Custom Provider to any Push channel. Add a Push channel, then open the Channel Settings modal.

“Custom” appears in the list of installed providers.

Add a title and blocks in the designer. Courier sends them to your webhook as plain text and as an array of blocks.

When the message sends, your webhook receives a payload like this:

interface TextBlock {
  type: "text";
  text: string;
}

interface ActionBlock {
  type: "action";
  url: string;
  text: string;
}

interface PushMessage {
  type: "push";
  data: {
  	messageId: string;
    content: {
      title: string;
      body: string;
      blocks: Array<ActionBlock | TextBlock>
    }
  }
}

{
  "type": "push",
  "data": {
    "messageId": "1-6140e057-2749378a31c6026f3dab823f",
    "content": {
      "blocks": [
        {
          "text": "My Body",
          "type": "text"
        },
        {
          "text": "Click Here",
          "url": "https://example.execute-api.us-east-1.amazonaws.com/dev/r/TRACKING_ID",
          "type": "action"
        }
      ],
      "body": "My Body\nClick Here: https://example.execute-api.us-east-1.amazonaws.com/dev/r/TRACKING_ID",
      "title": "My Title"
    }
  }
}

Profile requirements

No profile data is required. Courier posts the rendered message to your endpoint, and your endpoint decides how to address the recipient.

Overrides

covers the two levels and which one wins. An override changes what Courier sends to your custom provider. You can override the body, headers, method, and url fields. body is deep-merged into the request, so fields you leave out are still sent.

const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com",
    },
    providers: {
      custom: {
        override: {
          body: {},
          headers: {},
          method: "POST",
          url: "https://your-endpoint.example.com/webhook",
        },
      },
    },
  },
});

response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "email": "sarah@acme-corp.com",
        },
        "providers": {
            "custom": {
                "override": {
                    "body": {},
                    "headers": {},
                    "method": "POST",
                    "url": "https://your-endpoint.example.com/webhook",
                },
            },
        },
    },
)

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "email": "sarah@acme-corp.com"
      },
      "providers": {
        "custom": {
          "override": {
            "body": {},
            "headers": {},
            "method": "POST",
            "url": "https://your-endpoint.example.com/webhook"
          }
        }
      }
    }
  }'

response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com"
    },
    providers: {
      custom: {
        override: {
          body: {},
          headers: {},
          method: "POST",
          url: "https://your-endpoint.example.com/webhook"
        }
      }
    }
  }
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"custom": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{},
					"headers": map[string]any{},
					"method": "POST",
					"url": "https://your-endpoint.example.com/webhook",
				},
			},
		},
	},
})

SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().email("sarah@acme-corp.com").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("custom", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(),
                    "headers", java.util.Map.of(),
                    "method", "POST",
                    "url", "https://your-endpoint.example.com/webhook"
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);

$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'providers' => [
      'custom' => [
        'override' => [
          'body' => [],
          'headers' => [],
          'method' => 'POST',
          'url' => 'https://your-endpoint.example.com/webhook',
        ],
      ],
    ],
  ],
);

SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "custom",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {},
                          "headers": {},
                          "method": "POST",
                          "url": "https://your-endpoint.example.com/webhook"
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"custom": {"override": {"body": {}, "headers": {}, "method": "POST", "url": "https://your-endpoint.example.com/webhook"}}}'

With Courier MCP, send my template to sarah@acme-corp.com and override my custom provider's URL and body.

Provider details

custom

Courier recommends routing to the channel. Naming this key in routing.channels instead is supported, and sends through just this provider.

Send to a specific provider

When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

Get started

Available integrations

Build a custom provider for Courier

Prerequisites

Setup

Profile requirements

Overrides

Provider details

Send to a specific provider

​Prerequisites

​Setup

​Profile requirements

​Overrides

​Provider details

Send to a specific provider

Prerequisites

Setup

Profile requirements

Overrides

Provider details