Reference

Lookup

Public lookups: an address's card, WebFinger, health and this document.

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

WebFinger

GET /.well-known/webfinger

Called with .

Resolves acct:name@domain to the address's public card (RFC 7033). Served on each mail domain and on the API host.

Parameters

resource string, in query: acct:name@domain

Answers

200: Done
400: The request is malformed
404: Not found, or not yours to see

curl https://address.seleya.ai/api/.well-known/webfinger

import os, requests

r = requests.get(
    "https://address.seleya.ai/api/.well-known/webfinger",
)
print(r.status_code, r.json())

const r = await fetch("https://address.seleya.ai/api/.well-known/webfinger", {
  method: "GET",
});
console.log(r.status, await r.json());

This document

GET /openapi.json

Called with .

The API described in OpenAPI 3.1.

Answers

200: Done

curl https://address.seleya.ai/api/openapi.json

import os, requests

r = requests.get(
    "https://address.seleya.ai/api/openapi.json",
)
print(r.status_code, r.json())

const r = await fetch("https://address.seleya.ai/api/openapi.json", {
  method: "GET",
});
console.log(r.status, await r.json());

An address's public card

GET /v1/cards/{a}

Called with .

Who stands behind an address, whether that owner is verified, how to reach it and how to stop it mailing you.

Parameters

a string, in path required: The address, such as desk@acme.seleya.email.

Answers

200: Done
404: Not found, or not yours to see

Fields of the 200 answer

address string
display_name string
owner object
reach object
stop object
capabilities Capabilities

curl https://address.seleya.ai/api/v1/cards/desk@acme.seleya.email

import os, requests

r = requests.get(
    "https://address.seleya.ai/api/v1/cards/desk@acme.seleya.email",
)
print(r.status_code, r.json())

const r = await fetch("https://address.seleya.ai/api/v1/cards/desk@acme.seleya.email", {
  method: "GET",
});
console.log(r.status, await r.json());

Answer 200

{
  "address": "ct-a@beta.com",
  "display_name": "Contract agent A",
  "owner": {
    "name": "Acme (test company)",
    "proven_domain": "beta.com",
    "type": "company",
    "verification": "domain"
  },
  "reach": {
    "api": "https://address.seleya.ai/api/v1",
    "email": "ct-a@beta.com"
  },
  "stop": {
    "email": "ct-a@beta.com",
    "how": "Reply \"stop\" to any message from this address, and it never mails you again."
  }
}

Health

GET /v1/health

Called with .

Answers when the API is up.

Answers

200: Done

Fields of the 200 answer

ok boolean

curl https://address.seleya.ai/api/v1/health

import os, requests

r = requests.get(
    "https://address.seleya.ai/api/v1/health",
)
print(r.status_code, r.json())

const r = await fetch("https://address.seleya.ai/api/v1/health", {
  method: "GET",
});
console.log(r.status, await r.json());

Answer 200

{
  "ok": true
}

WebFinger on the API host

GET /v1/webfinger

Called with .

The same lookup, at the API host, for companies' own domains that point here.

Parameters

resource string, in query: acct:name@domain

Answers

200: Done
400: The request is malformed
404: Not found, or not yours to see

curl https://address.seleya.ai/api/v1/webfinger

import os, requests

r = requests.get(
    "https://address.seleya.ai/api/v1/webfinger",
)
print(r.status_code, r.json())

const r = await fetch("https://address.seleya.ai/api/v1/webfinger", {
  method: "GET",
});
console.log(r.status, await r.json());