Saltar al contenido
Esc
↑↓navegar↵abrir⌘Jvista previa

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
Autorización
AuthorizationToken Bearer · headerobligatorio

A BillionSend API key (bs_…).

Cuerpo de la solicitud
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)

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 propiedades
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 elementos
owner_addressesstring[]

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

máx. 50 elementos
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

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 elementos
Respuestas
201

Inbox created

objectstringobligatorio
Valores permitidos:inbox
idstring<uuid>obligatorio
namestringobligatorio
email_addressstringobligatorio
domain_idstring<uuid>obligatorio

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

receiving_addressstring | nullobligatorio
from_namestring | nullobligatorio
unreadintegerobligatorio

Threads with an unread message

draftsintegerobligatorio

Unsent drafts

last_receivedstring | nullobligatorio
created_atstringobligatorio
updated_atstringobligatorio
kindstringobligatorio
Valores permitidos:agenthuman
sharedbooleanobligatorio

On the shared inbox domain

expires_atstring | nullobligatorio
quarantinedintegerobligatorio

Held messages not yet released

pending_approvalintegerobligatorio

Drafts waiting for a person

401

Missing, malformed, unknown or revoked API key

statusCodenumberobligatorio
namestringobligatorio
messagestringobligatorio
403

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

statusCodenumberobligatorio
namestringobligatorio
messagestringobligatorio
409

The address is already used by an inbox

statusCodenumberobligatorio
namestringobligatorio
messagestringobligatorio
422

Validation error

statusCodenumberobligatorio
namestringobligatorio
messagestringobligatorio
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)

statusCodenumberobligatorio
namestringobligatorio
messagestringobligatorio
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

statusCodenumberobligatorio
namestringobligatorio
messagestringobligatorio
Pruébalo
Servidor
Autorización
Cuerpoapplication/json
Solicitud
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"
    ]
  }
}'
Respuesta
{
  "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
}

¿Te ha resultado útil esta página?