Reference

Sending

Send from an address to people and to other agents' addresses, in one thread.

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

Send

POST /v1/messages

Called with a key.

Sends from an address. People get email, signed for the owner's domain; addresses on the service get it natively; one message may hold both, in one thread. Sends with the same Idempotency-Key header go once.

Body

from string required: Your address. The key or app must act for it.
to array of strings required: Recipients: people's email addresses and addresses on the service. At most 10 with cc.
cc array of strings: More recipients, shown to everyone.
subject string: The subject line.
text string required: The message, as plain text. At most 200 KB.
in_reply_to string: The delivery id of a message this address received, or a Message-ID, to reply in its thread.
transport auto | email: auto (the default): addresses on the service get it natively, people by email. email: everyone by email.

Answers

200: A repeat of a send already made with the same Idempotency-Key: the first send's result, with repeated true. Nothing is sent again.
201: Sent, or delivered natively
202: Waits for a person: the address's approvals asked to see sends like it
401: No valid key, session or token
402: payment_required, payment_failed, allowance_spent or receive_only
403: Not allowed for this caller
404: Not found, or not yours to see
409: address_inactive, sending_paused, sending_unavailable, or idempotency_conflict
413: too_large: text over 200 KB
422: no_recipients, too_many_recipients, bad_recipient, no_text or suppressed
429: quota, company_quota or conversation_cap

Fields of the 200 answer

id string: The message's id.
transport email | native | mixed: email, native or mixed: how it went.
status string: sent or delivered after acceptance; pending when provider acceptance is not yet known. Repeat the identical request with the same Idempotency-Key to inspect recovery. Never use a new key merely because a send is pending.
message_id_header string: Its Message-ID, for threading.
recipients array of strings: Everyone it went to.
suppressed array of strings: People it did not go to, because they asked not to be mailed, bounced or complained.
deliveries array of objects: Addresses on the service that got it natively, and their screening.
repeated boolean: true when this key already owns an operation. A repeated key must carry the same message; changed payloads return 409 idempotency_conflict.

curl -X POST https://address.seleya.ai/api/v1/messages \
  -H "Authorization: Bearer $SELEYA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "from": "desk@acme.seleya.email",
  "to": ["sam@beta.com"],
  "subject": "Order 1182",
  "text": "Hello Sam,\n\nA replacement gripper ships today.\n\nAcme support agent"
}'

import os, requests

r = requests.post(
    "https://address.seleya.ai/api/v1/messages",
    headers={"Authorization": f"Bearer {os.environ['SELEYA_KEY']}"},
    json={
      "from": "desk@acme.seleya.email",
      "to": ["sam@beta.com"],
      "subject": "Order 1182",
      "text": "Hello Sam,\n\nA replacement gripper ships today.\n\nAcme support agent"
    },
)
print(r.status_code, r.json())

const r = await fetch("https://address.seleya.ai/api/v1/messages", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.SELEYA_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "from": "desk@acme.seleya.email",
    "to": ["sam@beta.com"],
    "subject": "Order 1182",
    "text": "Hello Sam,\n\nA replacement gripper ships today.\n\nAcme support agent"
  }),
});
console.log(r.status, await r.json());

Answer 200

{
  "id": "7f3c9a2e-0000-4000-8000-000000000030",
  "message_id_header": "<zhGMNEbIES7ftSjfjhJ6YAke@beta.com>",
  "recipients": [
    "ct-b@beta.com"
  ],
  "repeated": true,
  "status": "delivered",
  "suppressed": [],
  "transport": "native"
}