acme.sh can send notifications in its cronjob. Every night when the renew cronjob runs, you may receive notifications based on notify-level and notify-mode.

To configure notifications, use the --set-notify argument. This will send test notifications and update account.conf with the new settings.

  --notify-level  0|1|2|3           Set the notification level:  Default value is 2.

                 0: disabled, no notification will be sent.
                 1: send notification only when there is an error. No news is good news.
                 2: send notification when a cert is successfully renewed, or there is an error
                 3: send notification when a cert is skipped, renewed, or error. You will receive notification every night with this level.


  --notify-mode   0|1               Set notification mode. Default value is 0.

                  0: Bulk mode. Send all the domain's notifications in one message(email)
                  1: Cert mode. Send a message for every single cert. You may receive a bulk of emails in one night.

  --notify-hook   [hookname]        Set the notify hook

  --notify-source                   Set the server name in the notification message

The notifications can be emails or any other supported ways, such as requesting to a webhook, etc.

You can also implement your own hook.

See example: mailgun.sh or sendgrid.sh

acme.sh --set-notify  [--notify-hook mailgun]

acme.sh --set-notify  [--notify-level 2]
acme.sh --set-notify  [--notify-mode 0]


acme.sh --set-notify  [--notify-source myservername ]

There can be multiple --notify-hook parameters:

acme.sh --set-notify  --notify-hook mailgun  --notify-hook mail

And, all the parameters can be used together:

acme.sh --set-notify  --notify-hook mailgun  --notify-hook mail  \
  --notify-level 2 \
  --notify-mode 0

Send notification by mailgun.com api. The notification email will be sent to your email address.

Please register a free account at mailgun.com, you will get your api key.

If you don't have a domain, you can use the sandbox domain in your account. It looks like sandbox888888.mailgun.org. If you use the sandbox domain, you must add your receiving email address as an "Authorized recipient" https://app.mailgun.com/app/account/authorized

#The api key in your account.
export  MAILGUN_API_KEY="xxxxxxxx"

#The api domain, you can use the sandbox domain in your account.
export  MAILGUN_API_DOMAIN="xxxxxx.com"

#Optional,  the mail from address. it must be user@MAILGUN_API_DOMAIN
export  MAILGUN_FROM="[email protected]"

#The mail to address, which is to receive the notification.
export  MAILGUN_TO="[email protected]"

#Optional, if your mailgun account is in eu region, you must set MAILGUN_REGION
export  MAILGUN_REGION="us|eu"          #optional, use "us" as default

acme.sh --set-notify  --notify-hook  mailgun

export SENDGRID_API_KEY="xxxxxxxxxx"
export SENDGRID_FROM="[email protected]"
export SENDGRID_TO="[email protected]"
export SENDGRID_FROM_NAME="Email Sender Name" # Custom name other than the email FROM address configured above.

acme.sh --set-notify  --notify-hook sendgrid

Set it in your systems environment:

export MAIL_FROM="[email protected]" # or "Xxx Xxx <[email protected]>", currently works only with sendmail
export MAIL_TO="[email protected]"   # your account e-mail will be used as default if available

It will try to find and use sendmail, ssmtp, mutt, mail or msmtp automatically, if installed. (If you don't have any of these, you may be able to use smtp notifications instead.)

If you want to specify which application to use, please use MAIL_BIN:

export MAIL_BIN="sendmail"     # should be one of following: sendmail, ssmtp, mutt, mail or msmtp (with or without path)

Use the given account instead of the account named "default" in msmtp command.

export MAIL_MSMTP_ACCOUNT="account"

Ok, let's set notification hook:

acme.sh --set-notify  --notify-hook mail

The MAIL_BIN, MAIL_TO and MAIL_FROM will be saved in ~/.acme.sh/account.conf and will be reused when needed.

First get your Slack Webhook URL, then set it in your systems environment:

export SLACK_WEBHOOK_URL="..."
export SLACK_CHANNEL="..."     # overwrites Slack Webhook channel
export SLACK_USERNAME="..."    # overwrites Slack Webhook username

Ok, let's set notification hook:

acme.sh --set-notify  --notify-hook slack

The SLACK_WEBHOOK_URL, SLACK_CHANNEL and SLACK_USERNAME will be saved in ~/.acme.sh/account.conf and will be reused when needed.

Create a Slack app and allow the app to send messages by granting the chat:write permission. Once the app was allowed to send messages you need to install the app into your workspace.

Slack channel and the App token can be configured via the following environement variables:

export SLACK_APP_CHANNEL="..."
export SLACK_APP_TOKEN="xoxb-..."

Once the requried parameters have been configured you can setup the notification hook via the following command:

acme.sh --set-notify  --notify-hook slack_app

The SLACK_APP_CHANNEL and SLACK_APP_TOKEN will be saved in ~/.acme.sh/account.conf and will be reused when needed.

Send notification by postmarkapp.com API. The notification email will be sent to your email address. First get your token, then set it in your systems environment:

#The api token.
export  POSTMARK_TOKEN="xxxxxxxx"

#The mail to address.
export  POSTMARK_TO="[email protected]"

#The mail from address.
export  POSTMARK_FROM="[email protected]"

Ok, let's set notification hook:

acme.sh --set-notify  --notify-hook  postmark

The POSTMARK_TOKEN, POSTMARK_TO and POSTMARK_FROM will be saved in ~/.acme.sh/account.conf and will be reused when needed.

If there are any bugs for postmarkapp.com API, please report here: https://github.com/Neilpang/acme.sh/issues/2309

Send notification via pushover.net's api. The notification will be pushed to the specified pushover application.

Make a note of your PushOver user key from your account dashboard Create your pushover application at https://pushover.net/apps/build and note the API Token.

#The application token.
export PUSHOVER_TOKEN="xxxxxxxx"

#Your User key.
export PUSHOVER_USER="xxxxxxxx"

#Optional, name of a custom sound listed at https://pushover.net/api#sounds (Blank or not set will play default)
export PUSHOVER_SOUND="xxxxxxxx"

#Optional, name of a registered pushover client device, names are available on your dashboard. Default = "" (all devices)
export PUSHOVER_DEVICE="xxxxxxxx"

#Optional, Priority level of notification, Lowest Priority (-2), Low Priority (-1), Normal Priority (0), High Priority (1). Default=Normal Priority
export PUSHOVER_SOUND="x"

Ok, let's set notification hook:

acme.sh --set-notify  --notify-hook  pushover

The PUSHOVER_TOKEN, PUSHOVER_USER and PUSHOVER_SOUND will be saved in ~/.acme.sh/account.conf and will be reused when needed.

If there are any bugs for pushover.net notify, please report here: https://github.com/Neilpang/acme.sh/issues/2329

Send notification via IFTTT Webhooks so that you can make acme.sh work with tons of IFTTT services.

Firstly, connect our IFTTT to Webhooks service at https://ifttt.com/maker_webhooks and click "Documentation" in the top right corner to get the API key.

Secondly, create our IFTTT applet with Webhooks as this' and whatever as that', we'll setup the event name(e.g. acme_status) for this applet trigger.

Now we can set acme.sh notification hook:

#The API key.
export IFTTT_API_KEY="xxxx"

#Our event name, this should be same as the setting of your applet.
export IFTTT_EVENT_NAME="acme_status"

#Optional: the key of notification subject, available values are "value1", "value2", "value3", default "value1"
export IFTTT_SUBJECT_KEY="value1"

#Optional: the key of notification content, available values are "value1", "value2", "value3", default "value2"
export IFTTT_CONTENT_KEY="value2"

#Now we're ready to set notify hook
acme.sh --set-notify --notify-hook ifttt

The IFTTT_API_KEY, IFTTT_EVENT_NAME, IFTTT_SUBJECT_KEY and IFTTT_CONTENT_KEY will be saved in ~/.acme.sh/account.conf and will be reused when needed.

If there are any bugs for IFTTT Webhooks notify, please report here: https://github.com/Neilpang/acme.sh/issues/2421

Install sendxmpp manually or using your distributions package manager. Configure the sending account in ~/.sendxmpprc e.g.:

username: example
jserver: example.com
password: xxxxxxxx

Set it in your systems environment:

export XMPP_TO="[email protected]"                         # the xmpp account to send notifications to

Currently only sendxmpp is supported for sending notifications but support for similar tools can be added easily.

If you want to specify which application to use, please use XMPP_BIN:

export XMPP_BIN="/usr/bin/sendxmpp"                  # optional: override command to send xmpp messages
export XMPP_BIN_ARGS="--tls-ca-path=/etc/ssl/certs'" # optional: arguments for the xmpp command

Ok, let's set notification hook:

acme.sh --set-notify  --notify-hook xmpp

The XMPP_TO, XMPP_BIN and XMPP_BIN_ARGS will be saved in ~/.acme.sh/account.conf and will be reused when needed.

On debian based systems sendxmpp has problems validating certificates (see https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=854210).

Push notification to dingtalk group by group robot webhook api. First create a group robot, get your webhook url, and set a keyword.

推送通知到钉钉群聊天机器人. 先在群设置中添加一个 webhook 机器人. 获得 webhook url. 并设置一个 keyword. 目前不支持签名模式.

https://ding-doc.dingtalk.com/doc#/serverapi2/qf2nxq

export DINGTALK_WEBHOOK='https://oapi.dingtalk.com/robot/send?access_token=b05ccexxxxx'
export DINGTALK_KEYWORD=acme

acme.sh  --set-notify  --notify-hook dingtalk

通过 CoolQ 的插件 CQHTTP 将消息推送到 QQ。需要您自行部署 CQHTTP 服务端。部署详情参见 CoolQ 社区和 CQHTTP 的文档。

CoolQ 是一个第三方开发的无头 QQ 客户端，并提供了一些插件功能。在开始之前，您需要自行准备一个 QQ 号码作为机器人，并保证您的 QQ 和机器人 QQ 是好友关系以便发送通知。CQHTTP 是 CoolQ 的一个插件，为 CoolQ 提供了 HTTP API。

这个 hook 有四个环境变量可供传入:

• CQHTTP_TOKEN: 建议非空，将 CQHTTP 配置文件中您设置的 Access Token 填入。
• CQHTTP_USER: 必需，接收推送通知的 QQ 号码。您需要自行保证机器人号码可以向接收者的 QQ 号码发送消息。
• CQHTTP_APIROOT: 必需，您搭建的 CQHTTP 服务器的 URL (不包含斜杠结尾)。
• CQHTTP_CUSTOM_MSGHEAD: 可选，自定义的消息开头。默认值是 "A message from acme.sh:".

Push notifications to QQ via the plugin CQHTTP of CoolQ. A self-built CQHTTP server is needed. Visit the community of CoolQ and the docs of CQHTTP for the details of deployment.

CoolQ is a third-party headless QQ client, which provides a strong plugin system. Before we start, you need to prepare a QQ number for the robot. And ensure that your QQ number is a friend of the robot. CQHTTP is a plugin of CoolQ, which provides HTTP API for CoolQ.

This hook can parse four environment variables:

• CQHTTP_TOKEN: Recommend to be not empty, QQ application token, which is set in CQHTTP server.
• CQHTTP_USER: Required, QQ receiver ID. Make sure that the sender has right permission to send message to the receiver.
• CQHTTP_APIROOT: Required, CQHTTP Server URL (without slash suffix)
• CQHTTP_CUSTOM_MSGHEAD: Optional, custom message header. Default value is "A message from acme.sh:".

export CQHTTP_TOKEN="Itsjustat0ken,qwq"       # That's the access token
export CQHTTP_USER="10086"     # That's your QQ number (receiver)
export CQHTTP_APIROOT="http://cqhttp-server.local:5700"     # That's your server address

acme.sh  --set-notify  --notify-hook cqhttp

After that, you'll receive a message (在这之后，你将收到一条信息如下):

A message from acme.sh: Hello, this is a notification from acme.sh
If you receive this message, your notification works.

First get your Microsoft Teams Webhook URL, then set it in your systems environment:

export TEAMS_WEBHOOK_URL=""
export TEAMS_THEME_COLOR="586069"
export TEAMS_SUCCESS_COLOR="2cbe4e"
export TEAMS_ERROR_COLOR="cb2431"
export TEAMS_SKIP_COLOR="586069"

Ok, let's set notification hook:

acme.sh --set-notify  --notify-hook teams

The TEAMS_WEBHOOK_URL, TEAMS_THEME_COLOR, TEAMS_SUCCESS_COLOR, TEAMS_ERROR_COLOR and TEAMS_SKIP_COLOR will be saved in ~/.acme.sh/account.conf and will be reused when needed.

To omit default color set variable value to any non xdigit character, eg. TEAMS_SUCCESS_COLOR="-".

acme.sh can send email notifications by connecting directly to an SMTP mail server. Most commercial email service providers (ESPs) and corporate email systems support sending through SMTP, including Amazon SES, GSuite/Google Workspaces, Outlook.com, and others.

SMTP notification is available in acme.sh v2.8.9 or later. Please report bugs in the SMTP notify hook in issue #3358.

SMTP notifications in acme.sh require Python 3.4 or later, Python 2.7, or curl on the machine where you run acme.sh. (If you don't have Python or curl, you may be able to use mail notifications instead.)

First, get the SMTP connection information for your mail server or service. You'll need to know:

• the SMTP hostname (e.g., smtp.example.com) and port if non-standard (e.g., 587)
• type of secure connection required: "tls" (called STARTTLS or explicit TLS), "ssl" (called TLS wrapper or implicit TLS), or "none"
• whether authentication (login) is required, and if so the username and password to use

Set in your system environment:

# These are required:
export SMTP_FROM="[email protected]"  # just the email address (no display names)
export SMTP_TO="[email protected],[email protected]"  # just the email address, use commas between multiple emails
export SMTP_HOST="smtp.example.com"
export SMTP_SECURE="tls"  # one of "none", "ssl" (implicit TLS, TLS Wrapper), "tls" (explicit TLS, STARTTLS)

# The default port depends on SMTP_SECURE: none=25, ssl=465, tls=587.
# If your SMTP server uses a different port, set it:
export SMTP_PORT="2525"

# If your SMTP server requires AUTH (login), set:
export SMTP_USERNAME="<username>"
export SMTP_PASSWORD="<password>"

# acme.sh will try to use the python3, python2.7, or curl found on the PATH.
# If it can't find one, or to run a specific command, set:
export SMTP_BIN="/path/to/python_or_curl"

# If your SMTP server is very slow to respond, you may need to set:
export SMTP_TIMEOUT="30"  # seconds for SMTP operations to timeout, default 30

Ok, let's set notification hook:

acme.sh --set-notify --notify-hook smtp

If everything works, you will see a "success" message and receive a test email at the SMTP_TO address.

If you get an error message, it should explain what went wrong somewhere. The exact problem may be mixed in with less helpful error codes, so read through the message carefully. For additional troubleshooting, run the command again with --debug or --debug 2. (At debug level 2 or higher the output will show the complete SMTP session transcript, which may include the SMTP password.)

All of the SMTP_* settings will be saved in ~/.acme.sh/account.conf and will be reused when needed.

To have notifications delivered via Telegram, you first need to create a new Telegram bot, by talking to @BotFather within your Telegram client. Save the bot token that is returned after creation.

Next, you need the chat_id of your Telegram account (or a group). The simplest way to do this is to start a conversation with your new bot, and send a simple test message to it. Then, using curl, fetch the getUpdates API endpoint, and look for the chat id in the json object for the message you sent. For example:

$ bot_token="...." # enter your new bot's API token here.
$ curl -s "https://api.telegram.org/bot${bot_token}/getUpdates" | python -mjson.tool
{
    "ok": true,
    "result": [
        {
            "message": {
                "chat": {
                    "first_name": "Joe",
                    "id": 12345678,            <----- This is the Chat ID.
                    "last_name": "Bloggs",
                    "type": "private",
                    "username": "joebloggs"
                },
                ......
                "text": "text of the test message you sent",
                ......
<snip rest of output>
$

Once you have both the API token, and the chat ID for where you want the Bot to set notifications, set the following two variables to be used by the notification hook script:

export TELEGRAM_BOT_APITOKEN="..."   # Token returned by @BotFather during bot creation above.
export TELEGRAM_BOT_CHATID="..."     # Chat ID fetched above.

And then set notification hook:

acme.sh --set-notify --notify-hook telegram

Send notification via pushbullet.com's api. The notification will be pushed to the specified pushover application.

Create a Pushbullet API key at https://www.pushbullet.com/#settings/account.
If you want to send the push notification to a specific device, follow the instructions at https://docs.pushbullet.com/#list-pushes to get a list of all your devices, you should make note of the device iden field.

#Required, the application token. 
export PUSHBULLET_TOKEN="xxxxxxxx"

#Optional, Id of the specific device you want to send the notification
export PUSHBULLET_DEVICE="xxxxxxxx"

Ok, let's set notification hook:

acme.sh --set-notify  --notify-hook  pushbullet

The PUSHBULLET_TOKEN and PUSHBULLET_DEVICE will be saved in ~/.acme.sh/account.conf and will be reused when needed.

Send notification to feishu group via webhook api. First create a group robot, get your webhook url, and set a keyword.

推送通知到飞书群聊天机器人。先在群设置中添加一个群机器人，获得 webhook 地址，并设置一个关键字（目前暂不支持签名模式）。

API说明：https://open.feishu.cn/document/ukTMukTMukTM/ucTM5YjL3ETO24yNxkjN

export FEISHU_WEBHOOK='https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxxxxxxxxx'
export FEISHU_KEYWORD=acme

acme.sh --set-notify --notify-hook feishu

Send notification via Bark's API. The notification will be pushed to the specified pushover application.

Download Bark from App Store.

Open the app and get the API URL. It usually starts with "https://api.day.app/" and followed by a UUID of length 22. Set BARK_API_URL to the complete URL, which is in the format of "https://api.day.app/XXXXXXXXXXXXXXXXXXXXXX".

You can also use your own API server. Please refer to https://github.com/Finb/bark-server.

BARK_SOUND is an optional variable to set the sound of notification. Please refer to the app to get all available sounds.

BARK_GROUP is the group name of the notifications, which can be shown in the notification center of iOS.

export BARK_API_URL="https://api.day.app/XXXXXXXXXXXXXXXXXXXXXX"
export BARK_SOUND="newmail"
export BARK_GROUP=ACME

acme.sh --set-notify --notify-hook bark

Send notification to workwx group via webhook api. First create a group robot, get your webhook url, and set a keyword.

推送通知到企业微信群聊天机器人。先在群设置中添加一个群机器人，获得 webhook 地址，并设置一个关键字（目前暂不支持签名模式）。

API说明：https://developer.work.weixin.qq.com/document/path/91770

export WEIXIN_WORK_WEBHOOK='https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=693a91f6-7xxx-4bc4-97a0-0ec2sifa5aaa'
export WEIXIN_WORK_KEYWORD=acme

acme.sh --set-notify --notify-hook weixin_work

First, get your Discord Webhook URL, then set it in your systems environment:

export DISCORD_WEBHOOK_URL="..."
export DISCORD_AVATAR_URL="..."  # if empty, defaults to the defined avatar
export DISCORD_USERNAME="..."    # if empty, defaults to the defined username

Ok, let's set the notification hook:

acme.sh --set-notify  --notify-hook discord

The DISCORD_WEBHOOK_URL, DISCORD_AVATAR_URL, and DISCORD_USERNAME will be saved in ~/.acme.sh/account.conf and will be reused when needed.

First, get your CallmeBot Webhook URL, then set it in your systems environment:

export CALLMEBOT_YOUR_PHONE_NO="..."      # your phone no
export CALLMEBOT_API_KEY="..."

Ok, let's set the notification hook:

acme.sh --set-notify  --notify-hook callmebotWhatsApp

The CALLMEBOT_YOUR_PHONE_NO and CALLMEBOT_API_KEY will be saved in ~/.acme.sh/account.conf and will be reused when needed.

Notify via a custom shell script. The script is called with the following three parameters:

1. Subject
2. Message
3. Status code (0: success, 1: error 2: skipped)

To set the notification hook:

export CUSTOMSCRIPT_PATH="/usr/local/bin/acme-notification.sh"

acme.sh --set-notify --notify-hook customscript

The CUSTOMSCRIPT_PATH will be saved in ~/.acme.sh/account.conf and will be reused when needed.

Template for a custom script:

#!/usr/bin/env sh

subject="$1"
message="$2"
status="$3"

do-something "$subject ($status): $message"

First, you have determine what the "webhook" URL is for the channel or contact you'd like to notify. In the desktop app, the "manage webhooks" option in somewhat hidden under the "heading" for the channel or contact. Select the channel/contact and look in the middle of the page for a left arrow, the name, and a down arrow. Click on the down arrow, select "manage webhooks" and copy the URL to the clipboard.

Here are the step to configure Gchat notify:

export SAVED_GCHAT_WEBHOOK_URL='paste your webbook url here'

acme.sh --set-notify --notify-hook gchat

Uses AWS SES API (rather than SMTP credentials). You'll need to setup a API user with the following security permissions to send email.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "ses:SendEmail",
                "ses:SendRawEmail",
                "ses:SendBulkEmail"
            ],
            "Resource": "*"
        }
    ]
}

Usage:

export AWS_ACCESS_KEY_ID="sdfsdfsdfljlbjkljlkjsdfoiwje"
export AWS_SECRET_ACCESS_KEY="xxxxxxxxxxxxxx"
# Use the REGION column from the table
# https://docs.aws.amazon.com/general/latest/gr/ses.html
export AWS_SES_REGION="xx-xxxx-x" 
export AWS_SES_TO="[email protected]"
export AWS_SES_FROM="[email protected]"
# Custom name other than the email FROM address configured above (optional).
export AWS_SES_FROM_NAME="Something" 

acme.sh --set-notify  --notify-hook aws_ses

First, create a bot account on your Mattermost https://developers.mattermost.com/integrate/reference/bot-accounts/. Don't forget save bot's Access Token. Then set the environment variables. API "/posts" URL (current at https://api.mattermost.com/):

export MATTERMOST_API_URL=https://you_mattermost_server/api/v4/posts

Channel ID for notifications. Find the Channel ID in the Web Interface or Desktop Application by click View Info button.

export MATTERMOST_CHANNEL_ID=z1y2x3w4v5u6t7s8r1q2p3o4n5

Bot Token:

export MATTERMOST_BOT_TOKEN=a1b2c3d4e5f6g7h8i1j2k3l4m5

and finally turn on acme.sh notifications:

acme.sh --set-notify --notify-hook mattermost

Make sure to change NTFY_TOPIC to something that cannot be guessed easily.

export NTFY_URL="https://ntfy.sh"
export NTFY_TOPIC="xxxxxxxxxxxxx"

acme.sh --set-notify --notify-hook ntfy