zitadel/apps/docs/content/guides/manage/customize/notification-providers.mdx

---
title: SMS, SMTP and HTTP Provider for Notifications
sidebar_label: Notification Providers
---

ZITADEL can send messages to users via different notification providers, such as SMS, SMTP, or Webhook (HTTP Provider).
While you can add multiple providers to different channels, messages will only be delivered via the active provider.
Message and notification texts can be [customized](./texts) for an instance or for each organization.

## SMS providers

ZITADEL integrates with Twilio as SMS provider.

## SMTP providers

For easy configuration, there are some integration templates available such as:

- Amazon SES
- Mailgun
- Mailjet
- SendGrid
- ...

Aside from those, it is also possible to configure a generic SMTP provider. With a generic SMTP provider you specify what
the SMTP server, username and what kind of auth method you want to use. Currently, the Console only supports plain auth.
However, with [the API's](https://zitadel.com/docs/apis/resources/admin/admin-service-add-email-provider-smtp) you can
configure XOAUTH2 as well.

<Callout title="Default Provider ZITADEL Cloud">
A default SMTP provider is configured for ZITADEL Cloud customers.
This provider meant for development and testing purposes and you must replace this provider with your custom SMTP provider for production use cases to guarantee security and reliability of your service.
</Callout>

## Webhook / HTTP provider

Webhook (HTTP Provider) allows you to fully customize the messages and use integrate with any provider or custom solution to deliver the messages to users.
A provider with HTTP type will send the messages and the data to a pre-defined webhook as JSON.

### Configuring a HTTP provider

<Tabs>
  <Tab value="sms" label="SMS" default>

  First [add a new SMS Provider of type HTTP](/reference/api/admin/zitadel.admin.v1.AdminService.AddSMSProviderHTTP) to create a new HTTP provider that can be used to send SMS messages:

  ```bash
  curl -L 'https://${CUSTOM_DOMAIN}/admin/v1/sms/http' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer ${TOKEN}' \
    -d '{
      "endpoint": "http://relay.example.com/provider",
      "description": "provider description"
    }'
  ```

  Where `endpoint` defines the Webhook endpoint to which the data should be sent to.
  The result will contain an ID of the provider that we need in the next step.

  You can configure multiple SMS providers at the same time.
  To use the HTTP provider you need to [activate the SMS provider](/reference/api/admin/zitadel.admin.v1.AdminService.ActivateSMSProvider):

  ```bash
  curl -L 'https://${CUSTOM_DOMAIN}/admin/v1/sms/:id/_activate' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer ${TOKEN}' \
    -d '{}'
  ```

  The `id` is the provider's ID from the previous step.

  See full API reference for [SMS Providers](/reference/api/admin) for more details.

  </Tab>
  <Tab value="email" label="Email">

    First [add a new Email Provider of type HTTP](/reference/api/admin/zitadel.admin.v1.AdminService.AddEmailProviderHTTP) to create a new HTTP provider that can be used to send Email messages:

  ```bash
  curl -L 'https://${CUSTOM_DOMAIN}/admin/v1/email/http' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer ${TOKEN}' \
    -d '{
      "endpoint": "http://relay.example.com/provider",
      "description": "provider description"
    }'
  ```

  Where `endpoint` defines the Webhook endpoint to which the data should be sent to.
  The result will contain an ID of the provider that we need in the next step.

  You can configure multiple Email providers at the same time.
  To use the HTTP provider you need to [activate the Email provider](/reference/api/admin/zitadel.admin.v1.AdminService.ActivateEmailProvider):

  ```bash
  curl -L 'https://${CUSTOM_DOMAIN}/admin/v1/email/:id/_activate' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer ${TOKEN}' \
    -d '{}'
  ```

  The `id` is the provider's ID from the previous step.

  See full API reference for [Email Providers](/reference/api/admin/zitadel.admin.v1.AdminService.ListEmailProviders) for more details.

  </Tab>
</Tabs>

### HTTP provider payload

In case of the Twilio and Email providers, the messages will be sent as before, in case of the HTTP providers the content of the messages is the same but as a HTTP call.

Here an example of the body of an payload sent via Email HTTP provider:

```json
{
  "contextInfo": {
    "eventType": "user.human.initialization.code.added",
    "provider": {
      "id": "285181292935381355",
      "description": "test"
    },
    "recipientEmailAddress": "[email protected]"
  },
  "templateData": {
    "title": "Zitadel - Initialize User",
    "preHeader": "Initialize User",
    "subject": "Initialize User",
    "greeting": "Hello GivenName FamilyName,",
    "text": "This user was created in Zitadel. Use the username Username to login. Please click the button below to finish the initialization process. (Code 0M53RF) If you didn't ask for this mail, please ignore it.",
    "url": "http://example.zitadel.com/ui/login/user/init?authRequestID=\u0026code=0M53RF\u0026loginname=Username\u0026orgID=275353657317327214\u0026passwordset=false\u0026userID=285181014567813483",
    "buttonText": "Finish initialization",
    "primaryColor": "#5469d4",
    "backgroundColor": "#fafafa",
    "fontColor": "#000000",
    "fontFamily": "-apple-system, BlinkMacSystemFont, Segoe UI, Lato, Arial, Helvetica, sans-serif",
    "footerText": "InitCode.Footer"
  },
  "args": {
    "changeDate": "2024-09-16T10:58:50.73237+02:00",
    "code": "0M53RF",
    "creationDate": "2024-09-16T10:58:50.73237+02:00",
    "displayName": "GivenName FamilyName",
    "firstName": "GivenName",
    "lastEmail": "[email protected]",
    "lastName": "FamilyName",
    "lastPhone": "+41791234567",
    "loginNames": [
      "Username"
    ],
    "nickName": "",
    "preferredLoginName": "Username",
    "userName": "Username",
    "verifiedEmail": "[email protected]",
    "verifiedPhone": ""
  }
}
```

There are 3 elements to this message:

- `contextInfo`, with information on why this message is sent like the Event, which Email or SMS provider is used and which recipient should receive this message
- `templateData`, with all texts and format information which can be used with a template to produce the desired message
- `args`, with the information provided to the user which can be used in the message to customize