Email & SMS

Email and SMS hang off an identity — the persona is decided by where a message arrived, not by who sent it. Deliverability comes from a verified domain.

An inbox and a phone number are identity-level; the domain behind an inbox is org-level. One identity may hold several endpoints, and everything that arrives at any of them lands in the same message feed.

Email inboxes

The inbox object

string

Unique id (e.g. eml_01H...).

string

Always email_inbox.

string

The persona that owns the address.

string

The domain it is hosted on.

string

The full address, e.g. ava-sales@mail.acme.dev.

string

The part before the @.

string

Inbound routing keys off this: mail to the address wakes exactly this agent.

string

active or disabled.

string

Creation timestamp.

Create an inbox

POST /v1/identities/{id}/emails — scope agents:write Give either an explicit address or a domain_id — with domain_id the localpart is derived from the agent’s name (lowercased, hyphenated, capped at 32 characters, then suffixed -2, -3, … against what is taken).

string

required

The agent inbound mail wakes.

string

A full address to claim. The localpart must match [a-z0-9._-]{2,64}. Mutually exclusive with domain_id.

string

Host on this domain and auto-derive the localpart. Mutually exclusive with address.

curl -fsSL https://api.vetta.sh/v1/identities/idn_01H.../emails \
  -H "authorization: Bearer sk_live_..." \
  -H "content-type: application/json" \
  -d '{ "domain_id": "dom_01H9DM...", "owning_agent_id": "agt_01H..." }'

{
  "id": "eml_01H9EM...",
  "object": "email_inbox",
  "identity_id": "idn_01H...",
  "domain_id": "dom_01H9DM...",
  "address": "ava-sales@mail.acme.dev",
  "localpart": "ava-sales",
  "owning_agent_id": "agt_01H...",
  "status": "active",
  "created_at": "2026-08-20T17:05:00Z"
}

Errors — validation_failed (400) for a malformed localpart, or for supplying both address and domain_id; not_found (404) for an unknown identity, domain, or agent; conflict (409) when the address is already claimed.

List inboxes

GET /v1/identities/{id}/emails — scope agents:read. Returns a paginated list of inbox objects; accepts limit.

Delete an inbox

DELETE /v1/identities/{id}/emails/{eid} — scope agents:write. Mail to the address stops being accepted.

Send email

POST /v1/identities/{id}/emails/{eid}/send — scope sessions:write Gated on the domain’s dns_status. A send attempted before SPF/DKIM are provisioned is refused with a retryable job_not_ready — verify the domain and try again.

string[]

required

Recipient addresses.

string

required

Subject line.

string

required

Plain-text body.

Answers 202 with a receipt, not a message object — the provider’s own message id is deliberately not surfaced.

{
  "object": "email_send",
  "accepted": true,
  "from": "ava-sales@mail.acme.dev",
  "to": ["buyer@example.com"],
  "sent_at": "2026-08-20T17:06:00Z"
}

Errors — job_not_ready (409, retryable) while the domain is unverified; validation_failed (400); insufficient_credits (402).

Phone numbers

The phone number object

string

Unique id (e.g. pho_01H...).

string

Always phone_number.

string

The persona that owns the number.

string

The number in E.164 form, e.g. +14155550123.

string

ISO country code.

object

sms_inbound is live the moment the number is bought. sms_outbound is true iff campaign_status is approved. voice is always false — voice is not supported, and the field exists so its absence is explicit.

string

sole_prop or standard — the carrier registration tier.

string

none, pending_verification, verified, or rejected.

string

none, pending, approved, or rejected. Gates outbound.

string | null

When the carrier released the number.

string

Creation timestamp.

Provision a number

POST /v1/identities/{id}/phones — scope billing:write A number is a recurring charge, which is why this needs billing:write and not agents:write.

string

required

sole_prop or standard.

string

required

The registering entity, as the carrier will see it.

string

ISO country code. Defaults to US.

string

standard tier only. Write-through: handed to the carrier and never stored.

string

sole_prop only — the handset that receives the verification passcode. Never stored.

string

Request a specific number instead of the next available one.

Answers 202, not 201: the number exists and can receive immediately, but outbound waits on a carrier decision. Errors — validation_failed (400) when a tier-specific field is missing or supplied for the wrong tier; insufficient_credits (402); insufficient_scope (403) without billing:write.

List numbers

GET /v1/identities/{id}/phones — scope agents:read. Returns a paginated list; accepts limit.

Release a number

DELETE /v1/identities/{id}/phones/{pid} — scope billing:write. Stops the recurring charge. The number returns to the carrier and cannot be reclaimed.

Send SMS

POST /v1/identities/{id}/phones/{pid}/send — scope sessions:write

string

required

Recipient in E.164 form.

string

required

Message body.

Refused with compliance_pending until campaign_status is approved. That is a carrier rule, not a platform one — no scope or plan bypasses it, and inbound keeps working the whole time.

{
  "object": "sms_send",
  "accepted": true,
  "from": "+14155550123",
  "to": "+14155550188",
  "sent_at": "2026-08-20T17:07:00Z"
}

List inbound messages

GET /v1/identities/{id}/messages — scope agents:read Everything that arrived for this persona, both channels unless one is named.

string

email or sms. Omit for both.

integer

Page size. See Pagination.

string

Unique id (e.g. inb_01H...).

string

email or sms.

string

The eml_/pho_ endpoint it arrived at.

string

Sender address or number.

string

The endpoint address or number.

string | null

Email subject; null for SMS.

string

Plain-text body.

object

SPF/DKIM/DMARC results for mail, carrier origin for SMS — kept for the audit of why the message was accepted.

string | null

The session this message woke.

string

Arrival timestamp.

Inbound arrives at the platform’s own receivers — see Inbound receivers for how a message becomes a message object.

Identities

The persona these endpoints hang off.

Introduction

Core resources

Platform

Identity

Email inboxes

The inbox object

Create an inbox

List inboxes

Delete an inbox

Send email

Phone numbers

The phone number object

Provision a number

List numbers

Release a number

Send SMS

List inbound messages

Identities

​Email inboxes

​The inbox object

​Create an inbox

​List inboxes

​Delete an inbox

​Send email

​Phone numbers

​The phone number object

​Provision a number

​List numbers

​Release a number

​Send SMS

​List inbound messages

Identities

Email inboxes

The inbox object

Create an inbox

List inboxes

Delete an inbox

Send email

Phone numbers

The phone number object

Provision a number

List numbers

Release a number

Send SMS

List inbound messages