commit 4676ea2acb5a1129ec3c28ba660b60f19e2869ec from: Oliver Lowe date: Thu Apr 21 10:03:43 2022 UTC Add HTTP API reference, build automatically commit - 71bdede3e2286e895508fbbfe745eef880db6b7b commit + 4676ea2acb5a1129ec3c28ba660b60f19e2869ec blob - 70a96baa3e7659165e272377c67571412f35e57e blob + 26ca606503577fc68724b9691e1a068512b79e04 --- .build.yml +++ .build.yml @@ -1,7 +1,14 @@ image: openbsd/latest packages: - go + - node + - ruby-2.7.5 sources: - https://git.sr.ht/~otl/mailmux tasks: - test: cd mailmux && go test ./... + - docs: | + cp mailmux/docs/httpapiref.md slate/source/index.html.md + gem install bundler + bundle install + bundle exec middleman build blob - /dev/null blob + 5af8e3e5a81c2cd5ecd88534cf731e7c5465055b (mode 644) --- /dev/null +++ docs/httpapiref.md @@ -0,0 +1,209 @@ +--- +title: API Reference + +language_tabs: + - shell + +--- + +# Introduction + +The API is based on a REST API, similar to the one provided by [Stripe]. +Some requests can contain parameters, which should be URL-encoded forms in the request body. +Responses are JSON-encoded. + +[stripe]: https://stripe.com/docs/api + +# Authentication + +Authentication to the API is performed via [HTTP Basic Authentication][basicauth]. + +[basicauth]: https://datatracker.ietf.org/doc/html/rfc7617 + +# Errors + +```json +{ + "error": "lookup wonders_underbelly71: no such alias" +} +``` + +Responses to HTTP API requests include conventional HTTP status codes. +Briefly: codes beginning with 2 indicate success. +Codes beginning with 4 indicate some error with the client request. +Codes beginning with 5 indicate an error with the servers. + +In almost all cases, a JSON object with one key, `error`, is returned whose value +contains a description of what went wrong. + +# Registration + +``` +POST /v1/register +``` + +```shell +curl -u 'test@example.com:mysecret' https://mailmux.example.net/v1/aliases +``` + +Registration creates an account with the service. +The username must be a valid email address. +The username and password can be used for further API requests. + +## Parameters + +
+
username string
+
A full email address.
+
password string
+
A password with preferably at least 12 characters.
+
+ +# Aliases + +``` +POST /v1/aliases +GET /v1/aliases +GET /v1/aliases/:recipient +POST /v1/aliases/:recipient +DELETE /v1/aliases/:recipient +``` + +An Alias is used to route mail. +Any mail addressed to the recipient of the alias will be forwarded to its destination. + +## Alias object + +```json +{ + "Recipient": "wondering_underbelly71", + "Destination": "test@example.com", + "Expiry": 1845067777, + "Note": "newsletters for example.org" +} +``` + +An Alias has the following fields: + +
+
Recipient string
+
Just the username part of a publicly visible email address. +The domain(s) available for accepting mail depend on the SMTP server +implementation.
+
Destination string
+
Destination contains an email address, with domain suffix, +to which mail will be forwarded.
+
Expiry integer
+
Expiry specifies a time in seconds since the UNIX epoch +after which the alias is considered inactive; +that is, mail addressed to Recipient should be bounced.
+
Note string
+
Note contains user-defined text that can be used to, for example, identify the alias.
+
+ + +## Create an alias + +``` +POST /v1/aliases +``` + +```json +{ + "Recipient": "wondering_underbelly71", + "Destination": "test@example.com", + "Expiry": 1845067777, + "Note": "newsletters for example.org" +} +``` + +Creates an alias with recipient set to a unique randomly generated username. +If successful, the new alias object is returned. +Otherwise, an error is returned. + +### Parameters + +
+
Expiry optional integer
+
Expiry specifies a time in seconds since the UNIX epoch +after which the alias is considered inactive; +that is, mail addressed to Recipient should be bounced. +By default, aliases never expire.
+
Note optional string
+
Note contains user-defined text that can be used to, for example, identify the alias. +By default, aliases have no note.
+
+ +## Retrieve an alias + +``` +GET /v1/aliases/:recipient +``` + +```json +{ + "Recipient": "wondering_underbelly71", + "Destination": "test@example.com", + "Expiry": 1845067777, + "Note": "newsletters for example.org" +} +``` + +Retrieves the alias with the named recipient, if any. + +### Parameters + +None. + +## List aliases + +``` +GET /v1/aliases +``` + +```json +[ + { + "Recipient": "wondering_underbelly71", + "Destination": "test@example.com", + "Expiry": 1845067777, + "Note": "newsletters for example.org" + }, + { + "Recipient": "humble_anteater48", + "Destination": "test@example.com", + "Expiry": 1845067777, + "Note": "supermarket rewards card" + } +] +``` + +Returns all aliases for the current user. + +#### Parameters + +None. + +## Update an alias + +``` +POST /v1/aliases/:recipient +``` + +This is used to modify the named alias. + +### Parameters + +To unset parameters, set their values to the empty string (`""`). +This can be used to, for example, remove an alias' expiry time. + +
+
Expiry optional integer
+
Expiry specifies a time in seconds since the UNIX epoch +after which the alias is considered inactive; +that is, mail addressed to Recipient should be bounced. +By default, aliases never expire.
+
Note optional string
+
Note contains user-defined text that can be used to, for example, identify the alias. +By default, aliases have no note.
+