Hermes API Resources Python Docs

email.py

This resource provides a simple means of sending a given e-mail message to given e-mail addresses.

class meerkat_hermes.resources.email.Email

Bases: flask_restful.Resource

decorators = [<function authorise>]
endpoint = 'email'
mediatypes(resource_cls)
methods = ['PUT']
put()

Send an email with Amazon SES. First parse the given arguments to check it is a valid email. !!!Remember that whilst still in AWS “Sandbox” we can only send to verified emails.

Arguments are passed in the request data.

Parameters:
  • subject (str) – Required. The e-mail subject.
  • message (str) – Required. The e-mail message.
  • email (str) – The destination address/es for the e-mail.
  • subscriber_id (str) – The destination subscriber/s for the e-mail.
  • html (str) – The html version of the message, will default to the same as ‘message’.
  • from (str) – The sender’s address. Defaults to the config value SENDER.
Returns:

The amazon SES response.

log.py

This class enables management of the message log. It includes methods to get the entire log or to get a single

class meerkat_hermes.resources.log.Log

Bases: flask_restful.Resource

decorators = [<function authorise>]
delete(log_id)

Delete a log record from the database.

Parameters:log_id (str) – for the record to be deleted.
Returns:The amazon dynamodb response.
endpoint = 'log'
get(log_id)

Get message log records from the database.

Parameters:log_id (str) – The id of the desired message log.
Returns:The amazon dynamodb response.
mediatypes(resource_cls)
methods = ['DELETE', 'GET']

publish.py

This resource enables you to publish a message using given mediums to subscribers with subscriptions to given topics. It is expected to be the primary function of meerkat hermes.

class meerkat_hermes.resources.publish.Error

Bases: flask_restful.Resource

decorators = [<function authorise>]
endpoint = 'error'
mediatypes(resource_cls)
methods = ['PUT']
put()

Notify the developers of an error in the system. Error notifications can be posted to slack and sent out via email and text. These messages are not subject to the rate limiting that normal published messages are subject to.

Parameters:
  • message (str) – Required. The e-mail message.
  • subject (str) – Optional. Defaults to “Meerkat Error”.
  • medium ([str]) – Optional. A list of the following mediums: ‘email’, ‘sms’, ‘slack’. Defaults to [‘slack’,’email’].
  • sms-message (str) – Optional. The sms version of the message. Defaults to the same as ‘message’
  • html-message (str) – Optional. The html version of the message. Defaults to the same as ‘message’
Returns:

The amazon SES response.
class meerkat_hermes.resources.publish.Notify

Bases: flask_restful.Resource

decorators = [<function authorise>]
endpoint = 'notify'
get()

Notify the developers on slack of some change in the system. This is a GET endpoint that can be used by services like Read The Docs to update developers. All args are passed as GET args. Note that the auth token can be included in the get args.

Parameters:
  • message (str) – Required. The slack message.
  • subject (str) – Required. The message title.
Returns:

The amazon SES response.
mediatypes(resource_cls)
methods = ['GET', 'PUT']
put()

Notify the developers of some change in the system. Notifications are automatically sent to slack. These messages are not subject to the rate limiting that normal published messages are subject to.

Parameters:
  • message (str) – Required. The e-mail message.
  • subject (str) – Optional. Defaults to “Meerkat Notice”.
  • medium ([str]) – Optional. A list of the following mediums: ‘email’, ‘sms’, ‘slack’. Defaults to [‘slack’].
  • sms-message (str) – Optional. The sms version of the message. Defaults to the same as ‘message’
  • html-message (str) – Optional. The html version of the message. Defaults to the same as ‘message’
Returns:

The amazon SES response.
class meerkat_hermes.resources.publish.Publish

Bases: flask_restful.Resource

decorators = [<function authorise>]
endpoint = 'publish'
mediatypes(resource_cls)
methods = ['PUT']
put()

Publish a message to a given topic set. All subscribers with subscriptions to any of those topics are to receive the message. First parse the given arguments to check it is a valid email.

Arguments are passed in the request data.

Parameters:
  • id (str) – Required. If another message with the same ID has been logged, this one won’t send. Returns a 400 Bad Request error if this is the case.
  • message (str) – Required. The message.
  • topics ([str]) – Required. The topics the message fits into (determines destination address/es). Accepts array of multiple topics.
  • medium ([str]) – The medium by which to publish the message (‘email’, ‘sms’, etc…) Defaults to email. Accepts array of multiple mediums.
  • sms-message (str) – The sms version of the message. Defaults to the same as ‘message’
  • html-message (str) – The html version of the message. Defaults to the same as ‘message’
  • subject (str) – The e-mail subject. Defaults to “”.
  • from (str) –

    The address from which to send the message.

    Deafults to an emro address stored in the config.
Returns:

An array of amazon SES and nexmo responses for each message sent.

sms.py

This resource provides a simple means of sending a given e-mail message to given e-mail addresses.

class meerkat_hermes.resources.sms.Sms

Bases: flask_restful.Resource

decorators = [<function authorise>]
endpoint = 'sms'
mediatypes(resource_cls)
methods = ['PUT']
put()

Send an sms message with Nexmo. First parse the given arguments to check it is a valid sms.

Arguments are passed in the request data.

Parameters:
  • sms (str) – The destination phone number.
  • message (str) – The sms message.
Returns:

The Nexmo response.

subscribe.py

This class manages the Subscriber database field. It includes methods to update the the dynamodb table “hermes_subscribers”.

class meerkat_hermes.resources.subscribe.Subscribe

Bases: flask_restful.Resource

decorators = [<function authorise>]
delete(subscriber_id)

Delete a subscriber from the database.

Parameters:subscriber_id (str) – The ID for the subscriber to be deleted.
Returns:The amazon dynamodb response.
endpoint = 'subscribe'
get(subscriber_id)

Get a subscriber’s info from the database.

Parameters:subscriber_id (str) – The ID for the desired subscriber.
Returns:The amazon dynamodb response.
mediatypes(resource_cls)
methods = ['DELETE', 'GET', 'PUT']
put()

Add a new subscriber. Parse the given arguments to check it is a valid subscriber. Assign the subscriber a uuid in hex that is used to identify the subscriber when wishing to delete it. Does not use the subscriber_id argument.

Arguments are passed in the request data.

Parameters:
  • first_name (str) – Required. The subscriber’s first name.
  • last_name (str) – Required. The subscriber’s last name.
  • email (str) – Required. The subscriber’s email address.
  • country (str) – Required. The country that the subscriber has signed up to.
  • sms (str) – The subscribers phone number for sms.
  • slack (str) – The slack username/channel.
  • topics ([str]) – Required. The ID’s for the topics to which the subscriber wishes to subscribe.
  • verified (str) – Are their contact details verified? Defaults to False. str is resolved to boolean.
Returns:

The amazon dynamodb response, with the assigned subscriber_id.

unsubscribe.py

This class manages provides a public facing gateway to unsubscribe someone from the system. Specifically it provides a means for folk who know their subscriber ID, to unsubscribe themselves. A sutbale link can then be included in all messages that are sent out.

class meerkat_hermes.resources.unsubscribe.Unsubscribe

Bases: flask_restful.Resource

endpoint = 'unsubscribe'
get(subscriber_id)

Returns a page that allows the user to confirm they wish to delete their subscriptions

Parameters:subscriber_id (str) – The ID for the subscriber to be unsubscribed.
Returns:The amazon dynamodb response.
mediatypes(resource_cls)
methods = ['GET', 'POST']
post(subscriber_id)

Actually performs the deletion.

Parameters:subscriber_id (str) – The ID for the subscriber to be unsubscribed.
Returns:The amazon dynamodb response.

verify.py

If the subscriber hasn’t been verified, their subscriptions to different topics will not have been created. This resource provides a generic means forcreating and storing verify codes (one at a time) that can be used to verify any communication medium. It is also used after a subscriber’s details have been verified, to make their subscriptions active.

class meerkat_hermes.resources.verify.Verify

Bases: flask_restful.Resource

decorators = [<function authorise>]
endpoint = 'verify'
get(subscriber_id)

Sets the subscriber’s “verified” attribute to True.

Parameters:subscriber_id (str) – The ID for the subscriber who has been verified.
Returns:A json object with attribute “message” informing whether the verificaiton was successful e.g. {“message”:”Subscriber verified”}
mediatypes(resource_cls)
methods = ['GET', 'POST', 'PUT']
post()

Given a verify code, this method returns a boolean saying whether the given code matches the stored code.

Arguments are passed in the request data.

Post args: subscriber_id (str): Required. The ID for the subscriber who has been verified. code (str): Required. The code to be checked.

Returns:A json blob with one boolean attribute “matched” saying whether the codes have matched. e.g. {“matched”: true}
put()

Puts a new verify code into the verify attribute. This can then be checked using the post method and provides a generic means of verifying contact details for any communication medium.

Arguments are passed in the request data.

Parameters:
  • subscriber_id (str) – Required. The ID for the subscriber who has been verified.
  • code (str) – Required. The new code to be stored with the subscriber.
Returns:

The amazon dynamodb response.