Reference

Events

Signed webhooks that wake an agent when mail arrives or is held.

Calls go to https://address.seleya.ai/api. A refusal is {"error": {"code", "message"}} with its status; every code is in Errors.

Subscribe to events

POST /v1/subscriptions

Called with a key or a person signed in.

Subscribes a webhook to an address's events. Events carry ids only, signed with Standard Webhooks. The endpoint must echo a challenge before it is saved.

Body

address string required: The address whose events it receives.
url string required: An HTTPS endpoint that answers the challenge.

Answers

201: Made
401: No valid key, session or token
404: Not found, or not yours to see
422: A value is refused; the message says which

Fields of the 201 answer

id string
address string
url string
status string
secret string

curl -X POST https://address.seleya.ai/api/v1/subscriptions \
  -H "Authorization: Bearer $SELEYA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "address": "desk@acme.seleya.email",
  "url": "https://agent.acme.com/hooks/mail"
}'

import os, requests

r = requests.post(
    "https://address.seleya.ai/api/v1/subscriptions",
    headers={"Authorization": f"Bearer {os.environ['SELEYA_KEY']}"},
    json={
      "address": "desk@acme.seleya.email",
      "url": "https://agent.acme.com/hooks/mail"
    },
)
print(r.status_code, r.json())

const r = await fetch("https://address.seleya.ai/api/v1/subscriptions", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.SELEYA_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "address": "desk@acme.seleya.email",
    "url": "https://agent.acme.com/hooks/mail"
  }),
});
console.log(r.status, await r.json());

Answer 201

{
  "address": "ct-a@beta.com",
  "id": "7f3c9a2e-0000-4000-8000-000000000026",
  "secret": "whsec_…",
  "status": "active",
  "url": "https://juiw7rjojt3cahaammkuzf3di40ycqbj.lambda-url.eu-central-1.on.aws/ok/contract"
}

An address's subscriptions

GET /v1/subscriptions

Called with a key or a person signed in.

An address's webhook subscriptions.

Parameters

address string, in query: One address.

Answers

200: Done
401: No valid key, session or token
404: Not found, or not yours to see

Fields of the 200 answer

subscriptions array of objects

curl https://address.seleya.ai/api/v1/subscriptions \
  -H "Authorization: Bearer $SELEYA_KEY"

import os, requests

r = requests.get(
    "https://address.seleya.ai/api/v1/subscriptions",
    headers={"Authorization": f"Bearer {os.environ['SELEYA_KEY']}"},
)
print(r.status_code, r.json())

const r = await fetch("https://address.seleya.ai/api/v1/subscriptions", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.SELEYA_KEY}` },
});
console.log(r.status, await r.json());

Answer 200

{
  "subscriptions": [
    {
      "address_id": "7f3c9a2e-0000-4000-8000-000000000014",
      "failures": 0,
      "id": "7f3c9a2e-0000-4000-8000-000000000026",
      "status": "active",
      "url": "https://juiw7rjojt3cahaammkuzf3di40ycqbj.lambda-url.eu-central-1.on.aws/ok/contract"
    },
    {
      "address_id": "7f3c9a2e-0000-4000-8000-000000000014",
      "failures": 0,
      "id": "7f3c9a2e-0000-4000-8000-000000000027",
      "status": "failed",
      "url": "https://example.com/no-echo"
    }
  ]
}

Revoke a subscription

DELETE /v1/subscriptions/{id}

Called with a key or a person signed in.

Ends a subscription; no more events go to its URL.

Parameters

id string, in path required: Its id.

Answers

204: Done, with no body
401: No valid key, session or token
404: Not found, or not yours to see

curl -X DELETE https://address.seleya.ai/api/v1/subscriptions/ID \
  -H "Authorization: Bearer $SELEYA_KEY"

import os, requests

r = requests.delete(
    "https://address.seleya.ai/api/v1/subscriptions/ID",
    headers={"Authorization": f"Bearer {os.environ['SELEYA_KEY']}"},
)
print(r.status_code, r.text)

const r = await fetch("https://address.seleya.ai/api/v1/subscriptions/ID", {
  method: "DELETE",
  headers: { Authorization: `Bearer ${process.env.SELEYA_KEY}` },
});
console.log(r.status);