Zum Inhalt springen
Esc
↑↓navigieren↵öffnen⌘Jvorschau

Create an inbox

An address that receives into threads, on one of your verified domains (receiving on, or forwarding: true) or, with email_address omitted, an address on the shared inbox domain that needs no DNS: username names it, or it is random. domain_id takes a row of GET /domains instead of email_address: the team’s shared subdomain, or one of your domains with username. It never expires unless expires_in says so. Returns the full inbox. BillionSend extensions: username, domain_id, kind (agent by default), expires_in and safety.

POST/inboxes
Autorisierung
AuthorizationBearer-Token · headererforderlich

A BillionSend API key (bs_…).

Request-Body
application/json
email_addressstring

An address on one of your verified domains; it needs receiving on unless forwarding is true. BillionSend extension: omitted, the inbox gets an address on the shared inbox domain (no DNS), named by username or random, unless domain_id names one of your domains.

domain_idstring<uuid>

BillionSend extension: the id of a GET /domains row, instead of email_address. The team's subdomain of the shared domain (the row with shared: true) is the same as leaving email_address out; one of your verified domains needs username, the part before the @.

usernamestring

BillionSend extension: with email_address omitted, the part before the @ of the shared-domain address, trimmed and lowercased: 1-64 letters, digits, dots, hyphens and underscores, starting and ending with a letter or digit, never cut short. Reserved names (postmaster, abuse, admin, security, support, noreply, no-reply, billing, hostmaster, webmaster, mailer-daemon, root, compared without dots, hyphens and underscores), the fwd- prefix and brand look-alikes answer 422, and one already in use 409. A chosen name is reviewed first: 503 with retry-after while that review is unavailable. Omitted: a random one. With a domain_id of one of your domains, it is the part before the @ there, required, under email_address's rule.

namestring

Internal name, 1-320 characters, so any address fits. Defaults to email_address.

from_namestring

The name recipients see, a plain name (not "Name <email>"); "" leaves it unset. On the shared domain it may not imitate a brand, and it is reviewed like username.

forwardingboolean

Receive without an MX record: mail forwarded to the inbox's receiving_address lands in it

kindstring

BillionSend extension: agent (default; threads, screening, drafts that wait for approval) or human (a team mailbox)

Erlaubt:agenthuman
expires_instring | null

BillionSend extension: a lifetime counted from now, "1h" to "365d"; omitted or null, the inbox never expires. A shared-domain inbox left unused for 90 days (no mail in or out, no API calls on it) is deleted either way.

safetyInboxSafetyPatch

BillionSend extension: safety rules over the kind's defaults

Eigenschaften anzeigen
accept_fromstring

Who may write in: anyone; verified (DMARC-aligned senders, known threads, the allowlist); allowlist only. Mail that fails is quarantined.

Erlaubt:anyoneverifiedallowlist
allowliststring[]

"local@domain" (exact) or "*@domain" (the domain and its subdomains). On the shared domain it only lets mail in

max. 500 Elemente
owner_addressesstring[]

Owners besides the team members' login addresses; ignored on the shared domain

max. 50 Elemente
screeningboolean

Score external mail for prompt injection (agent inboxes only)

extract_codesboolean

Expose extracted codes and sign-in links

send_policystring

What the inbox may send without a person's approval. On the shared domain "allowlist" answers 422, and so does "open" unless the team is on a paid plan and past its first sends

Erlaubt:reply_onlyallowlistopen
require_approvalboolean

Every send waits for a person

private_codesboolean

Received codes and sign-in links can't be sent on to anyone but owners

send_capinteger | null

Unattended recipients per UTC day; null: no cap. 1-50 on the shared domain

forward_tostring[]

Forward every delivered message to these team member or owner addresses; team members only on the shared domain

max. 5 Elemente
Antworten
201

Inbox created

objectstringerforderlich
Erlaubt:inbox
idstring<uuid>erforderlich
namestringerforderlich
email_addressstringerforderlich
domain_idstring<uuid>erforderlich

A shared address's is its team's shared subdomain: the GET /domains row with shared: true

receiving_addressstring | nullerforderlich
from_namestring | nullerforderlich
unreadintegererforderlich

Threads with an unread message

draftsintegererforderlich

Unsent drafts

last_receivedstring | nullerforderlich
created_atstringerforderlich
updated_atstringerforderlich
kindstringerforderlich
Erlaubt:agenthuman
sharedbooleanerforderlich

On the shared inbox domain

expires_atstring | nullerforderlich
quarantinedintegererforderlich

Held messages not yet released

pending_approvalintegererforderlich

Drafts waiting for a person

401

Missing, malformed, unknown or revoked API key

statusCodenumbererforderlich
namestringerforderlich
messagestringerforderlich
403

The plan's inbox limit, or a restricted API key

statusCodenumbererforderlich
namestringerforderlich
messagestringerforderlich
409

The address is already used by an inbox

statusCodenumbererforderlich
namestringerforderlich
messagestringerforderlich
422

Validation error

statusCodenumbererforderlich
namestringerforderlich
messagestringerforderlich
429

Too many inboxes created in the last hour, or too many names reviewed or refused on the shared domain today, or the rate limit (rate_limit_exceeded, with Retry-After)

statusCodenumbererforderlich
namestringerforderlich
messagestringerforderlich
503

A chosen username or from_name on the shared domain can't be reviewed right now, or the team's subdomain on the shared domain is still waiting for its name review; retry-after says when to try again

statusCodenumbererforderlich
namestringerforderlich
messagestringerforderlich
Ausprobieren
Server
Autorisierung
Bodyapplication/json
Anfrage
curl -X POST 'https://api.billionsend.com/inboxes' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "email_address": "string",
  "domain_id": "b2f7354f-b74d-4332-ab10-1a5e3c56466c",
  "username": "string",
  "name": "string",
  "from_name": "string",
  "forwarding": true,
  "kind": "agent",
  "expires_in": "string",
  "safety": {
    "accept_from": "anyone",
    "allowlist": [
      "string"
    ],
    "owner_addresses": [
      "string"
    ],
    "screening": true,
    "extract_codes": true,
    "send_policy": "reply_only",
    "require_approval": true,
    "private_codes": true,
    "send_cap": 0,
    "forward_to": [
      "string"
    ]
  }
}'
Antwort
{
  "object": "inbox",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "email_address": "string",
  "domain_id": "b2f7354f-b74d-4332-ab10-1a5e3c56466c",
  "receiving_address": "string",
  "from_name": "string",
  "unread": 0,
  "drafts": 0,
  "last_received": "string",
  "created_at": "string",
  "updated_at": "string",
  "kind": "agent",
  "shared": true,
  "expires_at": "string",
  "quarantined": 0,
  "pending_approval": 0
}

War diese Seite hilfreich?