Notification Service


The notification service listens for tasks with associated notifications and handles requests to send emails and post pulse messages.

Functions

Using the APIs
SignatureSummary
ping() : voidPing Server
email(payload) : voidSend an Email
pulse(payload) : voidPublish a Pulse Message
irc(payload) : voidPost IRC Message
addDenylistAddress(payload) : voidDenylist Given Address
deleteDenylistAddress(payload) : voidDelete Denylisted Address
list({continuationToken, limit}) : resultList Denylisted Notifications

Ping Server

Method
get
Route
/ping
Signature
ping() : void
Stability
stable

Respond without doing anything. This endpoint is used to check that the service is up.



Send an Email

(experimental)

Method
post
Route
/email
Scopes
notify:email:<address>
Signature
email(payload) : void
Stability
experimental

Send an email to address. The content is markdown and will be rendered to HTML, but both the HTML and raw markdown text will be sent in the email. If a link is included, it will be rendered to a nice button in the HTML version of the email

Request Payload

Send Email Request (source)

Request to send an email

addressstring

E-mail address to which the message should be sent

subjectstring[1:255]

Subject line of the e-mail, this is plain-text

contentstring[1:102400]

Content of the e-mail as markdown, will be rendered to HTML before the email is sent. Notice that markdown allows for a few HTML tags, but won't allow inclusion of script tags and other unpleasantries.

linkObject of

Optional link that can be added as a button to the email.

textstring[1:40]

Text to display on link.

hrefstring[1:1024]uri

Where the link should point to.

replyTostring

Reply-to e-mail (this property is optional)

templatestring
default: simple
  • simple
  • fullscreen

E-mail html template used to format your content.



Publish a Pulse Message

(experimental)

Method
post
Route
/pulse
Scopes
notify:pulse:<routingKey>
Signature
pulse(payload) : void
Stability
experimental

Publish a message on pulse with the given routingKey.

Request Payload

Post Pulse Message Request (source)

Request to post a message on pulse.

routingKeystring[0:255]

Routing-key to use when posting the message.

messageObject of

IRC message to send as plain text.

Anything ¯\_(ツ)_/¯


Post IRC Message

(experimental)

Method
post
Route
/irc
Scopes
if  channelRequest
notify:irc-channel:<channel>
else
notify:irc-user:<user>
Signature
irc(payload) : void
Stability
experimental

Post a message on IRC to a specific channel or user, or a specific user on a specific channel.

Success of this API method does not imply the message was successfully posted. This API method merely inserts the IRC message into a queue that will be processed by a background process. This allows us to re-send the message in face of connection issues.

However, if the user isn't online the message will be dropped without error. We maybe improve this behavior in the future. For now just keep in mind that IRC is a best-effort service.

Request Payload

Post IRC Message Request (source)

Request to post a message on IRC.

Post IRC Message RequestOne of

Request to post a message on IRC.

Channel MessageObject of
channelstring[1:∞]^[#&][^ ,\u0007]{1,199}$

Channel to post the message in.

messagestring[1:510]

IRC message to send as plain text.

Private MessageObject of
userstring[1:255]^[A-Za-z\[\]\\~_\^{|}][A-Za-z0-9\-\[\]\\~_\^{|}]{0,254}$

User to post the message to.

messagestring[1:510]

IRC message to send as plain text.



Denylist Given Address

(experimental)

Method
post
Route
/denylist/add
Scopes
notify:manage-denylist:<notificationType>/<notificationAddress>
Signature
addDenylistAddress(payload) : void
Stability
experimental

Add the given address to the notification denylist. The address can be of either of the three supported address type namely pulse, email or IRC(user or channel). Addresses in the denylist will be ignored by the notification service.

Request Payload

Notificaiton Type And Address (source)

Type of notification and its corresponding address.

notificationTypestring
  • email
  • pulse
  • irc-user
  • irc-channel
notificationAddressstring


Delete Denylisted Address

(experimental)

Method
delete
Route
/denylist/delete
Scopes
notify:manage-denylist:<notificationType>/<notificationAddress>
Signature
deleteDenylistAddress(payload) : void
Stability
experimental

Delete the specified address from the notification denylist.

Request Payload

Notificaiton Type And Address (source)

Type of notification and its corresponding address.

notificationTypestring
  • email
  • pulse
  • irc-user
  • irc-channel
notificationAddressstring


List Denylisted Notifications

(experimental)

Method
get
Route
/denylist/list
Signature
list({continuationToken, limit}) : result
Stability
experimental

Lists all the denylisted addresses.

By default this end-point will try to return up to 1000 addresses in one request. But it may return less, even if more tasks are available. It may also return a continuationToken even though there are no more results. However, you can only be sure to have seen all results if you keep calling list with the last continuationToken until you get a result without a continuationToken.

If you are not interested in listing all the members at once, you may use the query-string option limit to return fewer.

Response

List of notification adresses (source)

List of notification addresses.

addressesArray of
notificationTypestring
  • email
  • pulse
  • irc-user
  • irc-channel
notificationAddressstring
continuationTokenstring

A continuation token is returned if there are more results than listed here. You can optionally provide the token in the request payload to load the additional results.