Publish notifications using ntfy.sh from Emacs
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
Shom Bandopadhaya d78077d7be Documented issue with special characters in URL. 7 months ago
.build.yml Build readme file for sourcehut through build automation 7 months ago
LICENSE Added license file 7 months ago
ntfy.el Added features to set header and tag, improved documentation. 7 months ago
readme.org Documented issue with special characters in URL. 7 months ago

readme.org

ntfy.el - Send notifications from Emacs using ntfy.sh

Overview

This is a small package to provide an interface to use the https://ntfy.sh service (or self-hosted version) to send notification from Emacs. The initial use case is to send quick notifications from emacs to a mobile device (ntfy only support Android currently) as reminders. The ntfy-send-message can also be utilized to send notifications from other functions.

Installation and configuration

Installation

The ntfy.el file can be downloaded and loaded via load-file and other installation means.

Recommended: the package can be installed and configured using straight.el using:

(use-package ntfy
  :straight (ntfy :type git :host nil :repo "https://git.sr.ht/~shom/ntfy")
  :config (setq ntfy-server "https://ntfy.sh"
		ntfy-topic "mytopic"
		ntfy-header "Notification from emacs"
		ntfy-tags "purple_circle,loudspeaker"))

Configuration

The following custom variables must be configured:

  • nfty-server: The URL of the server (including the https:// part), ntfy.sh generously offers a free hosted version so it can be set to https://ntfy.sh, be please be mindful of how we use this free resource and review the privacy policy of the service.
  • nfty-topic: The topic or channel where the notification should be published. If using the public ntfy.sh service, ensure that is not an easily guessable topic.
  • ntfy-header: This is the title of the notification, the message is sent as the body of the notification.
  • ntfy-tags: The emoji(s) that'll appear before the header message. Use comma separated (no spaces) string, see https://ntfy.sh/docs/publish/#tags-emojis for details.

Usage

Once the package is loaded and configured a notification can be sent by invoking the following commands interactively or programmatically:

Interactive Programmatic
ntfy-send-message (ntfy-send-message MESSAGE)
ntfy-send-message-with-header (ntfy-send-message-with-header HEADER MESSAGE)
ntfy-send-message-with-header-and-tags (ntfy-send-message-with-header-and-tags TAGS HEADER MESSAGE)
ntfy-send-url (ntfy-send-url URL)

Improvements

This is the first Emacs package I've put together, contributions, suggestions for best practices, and constructive criticism is very much welcome and appreciated.

Here are some of the potential improvements:

  • Improve documentation and testing.

    • This has been tested on Emacs 27.2 & 28.0.92 using curl on Pop!_OS (20.04 and 22.04) and Termux.
    • All functions are documented and there are no Flycheck errors or warnings.
    • Test on other OSes.
  • Provide more functionality:

    • Interactively and programmatically set the tag per message as an optional parameter.
    • Send URL as a clickable item from the Android notification shade.

      • Special characters break this function. Might need to switch to JSON, can't url-encode curl header.
    • Send a file attachment.
    • Send Android intents.
    • Stretch:

      • Provide templates for Header and Tags as a pop-up selection list.
      • Provide minor mode to capture all Emacs notifications and post them to pre-defined topics.