Email Notification

Note

This page covers the system’s outbound notification email configuration: the SMTP (or local MTA) settings Zammad uses to send its own internal notifications, like “you were assigned a ticket”, plus the local sender identity (EmailAddress) that gets attached to it. This is distinct from a ticket mailbox / support-inbox channel (Admin → Channels → Email, for customer correspondence), which is a separate feature not covered by this page.

List

Required permission: admin.channel_email

GET-Request sent: /api/v1/channels_email

This is a combined index: it returns the notification channel(s), the ticket mailbox channel(s) (empty in this example) and the local sender addresses in one response. The response below is trimmed to the fields relevant to notification email configuration.

Response:

# HTTP-Code 200 Ok

{
   "notification_channel_ids": [1],
   "account_channel_ids": [],
   "email_address_ids": [1],
   "assets": {
      "Channel": {
         "1": {
            "id": 1,
            "group_id": null,
            "area": "Email::Notification",
            "options": {
               "outbound": {
                  "adapter": "smtp",
                  "options": {
                     "host": "smtp.example.com",
                     "port": 25,
                     "ssl": true,
                     "user": "",
                     "password": "",
                     "domain": "zammad.example.com"
                  }
               }
            },
            "active": true
         },
         "2": {
            "id": 2,
            "group_id": null,
            "area": "Email::Notification",
            "options": {
               "outbound": {"adapter": "sendmail"}
            },
            "active": false
         }
      }
   },
   "channel_driver": {
      "email": {
         "inbound": {"imap": "IMAP", "pop3": "POP3"},
         "outbound": {
            "smtp": "SMTP - configure your own outgoing SMTP settings"
         }
      }
   },
   "config": {
      "notification_sender": "\"Zammad Helpdesk\" <noreply@zammad.example.com>"
   }
}

Note

Only one channel can be active: true per notification setup at a time. Configuring a new one (see Configure below) automatically deactivates whichever one was previously active, in the response above, sendmail (id 2) is now active: false because smtp (id 1) was configured afterward.

Configure

Required permission: admin.channel_email

POST-Request sent: /api/v1/channels_email_notification

Note

Pass the adapter settings in a top-level options key as shown below. Other key names, such as new_configuration (the parameter name of the internal service class Service::System::SetEmailNotificationConfiguration), are not rejected with a validation error. The request fails with an unhandled undefined method 'key?' for nil error instead.

{
   "adapter": "smtp",
   "options": {
      "host": "smtp.example.com",
      "port": 25,
      "ssl": true,
      "user": "",
      "password": ""
   }
}

Response:

# HTTP-Code 200 Ok

{
   "result": "ok"
}

Note

This call does double duty: it tests the connection live, sending a real test email as a side effect, and if the test succeeds, saves the configuration as the active notification channel in the same call. There is no separate “save” step; notification_channel_ids in /api/v1/channels_email immediately reflects the new channel.

Note

POST /api/v1/channels_email_probe is not an alternative to this endpoint for a notification-only setup. It always validates a full inbound and outbound mailbox (EmailHelper::Probe.full). Sending outbound-only SMTP settings to it returns {"result": "failed", "reason": "inbound failed"}, even when the outbound settings are correct.

Sender Address

The local sender identity used for outbound notification email is managed as an EmailAddress resource.

List

Required permission: admin.channel_email or ticket.agent

GET-Request sent: /api/v1/email_addresses

Returns an array of objects, each shaped like the single object shown in the Show response below.

Show

Required permission: admin.channel_email or ticket.agent

GET-Request sent: /api/v1/email_addresses/{id}

Response:

# HTTP-Code 200 Ok

{
   "id": 1,
   "channel_id": 1,
   "name": "Zammad Support",
   "email": "zammad@example.com",
   "active": true,
   "note": "Default outbound sender address.",
   "preferences": null,
   "updated_by_id": 3,
   "created_by_id": 3,
   "created_at": "2026-09-24T12:32:20.671Z",
   "updated_at": "2026-09-24T12:32:20.671Z",
   "group_ids": []
}

Create

Required permission: admin.channel_email

POST-Request sent: /api/v1/email_addresses

Note

channel_id must reference the id of the active notification channel from List/Configure above.

{
   "email": "zammad@example.com",
   "name": "Zammad Support",
   "channel_id": 1,
   "note": "Default outbound sender address."
}

Response:

# HTTP-Code 201 Created

{
   "id": 1,
   "channel_id": 1,
   "name": "Zammad Support",
   "email": "zammad@example.com",
   "active": true,
   "note": "Default outbound sender address.",
   "preferences": null,
   "updated_by_id": 3,
   "created_by_id": 3,
   "created_at": "2026-09-24T12:32:20.671Z",
   "updated_at": "2026-09-24T12:32:20.671Z",
   "group_ids": []
}

Note

group_ids here reflects which Groups have their outbound mail pointed at this address. That’s set separately, via PUT /api/v1/groups/{id} with {"email_address_id": <this id>}, it isn’t part of this resource’s own payload.

Update

Required permission: admin.channel_email

PUT-Request sent: /api/v1/email_addresses/{id}

Same payload shape as Create above. Sending the full Create payload to an existing address’s id updates that record in place. It doesn’t create a duplicate. Response is the updated record, same shape as the Create response above.

Delete

Required permission: admin.channel_email

Danger

This is a permanent removal

Please note that removing email addresses cannot be undone.

Groups that use the deleted address as their sender address (email_address_id) are reset to no sender address.

DELETE-Request sent: /api/v1/email_addresses/{id}

Response:

# HTTP-Code 200 Ok

{}