Pular para o conteúdo
Esc
↑↓navegar↵abrir⌘Jpré-visualizar

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
Autorização
AuthorizationToken Bearer · headerobrigatório

A BillionSend API key (bs_…).

Corpo da requisição
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. Where the instance reviews names, a chosen one 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)

Valores permitidos: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

Mostrar propriedades
accept_fromstring

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

Valores permitidos:anyoneverifiedallowlist
allowliststring[]

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

máx. 500 itens
owner_addressesstring[]

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

máx. 50 itens
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 instance lets the team start conversations there (paid plans only)

Valores permitidos: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

máx. 5 itens
Respostas
201

Inbox created

objectstringobrigatório
Valores permitidos:inbox
idstring<uuid>obrigatório
namestringobrigatório
email_addressstringobrigatório
domain_idstring<uuid>obrigatório

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

receiving_addressstring | nullobrigatório
from_namestring | nullobrigatório
unreadintegerobrigatório

Threads with an unread message

draftsintegerobrigatório

Unsent drafts

last_receivedstring | nullobrigatório
created_atstringobrigatório
updated_atstringobrigatório
kindstringobrigatório
Valores permitidos:agenthuman
sharedbooleanobrigatório

On the shared inbox domain

expires_atstring | nullobrigatório
quarantinedintegerobrigatório

Held messages not yet released

pending_approvalintegerobrigatório

Drafts waiting for a person

401

Missing, malformed, unknown or revoked API key

statusCodenumberobrigatório
namestringobrigatório
messagestringobrigatório
403

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

statusCodenumberobrigatório
namestringobrigatório
messagestringobrigatório
409

The address is already used by an inbox

statusCodenumberobrigatório
namestringobrigatório
messagestringobrigatório
422

Validation error

statusCodenumberobrigatório
namestringobrigatório
messagestringobrigatório
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)

statusCodenumberobrigatório
namestringobrigatório
messagestringobrigatório
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

statusCodenumberobrigatório
namestringobrigatório
messagestringobrigatório
Experimentar
Servidor
Autorização
Corpoapplication/json
Requisição
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"
    ]
  }
}'
Resposta
{
  "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
}

Esta página foi útil?