Aller au contenu
Esc
↑↓naviguer↵ouvrir⌘Japerçu

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
Autorisation
AuthorizationJeton Bearer · headerrequis

A BillionSend API key (bs_…).

Corps de la requête
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)

Valeurs autorisées :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

Afficher les propriétés
accept_fromstring

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

Valeurs autorisées :anyoneverifiedallowlist
allowliststring[]

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

max 500 éléments
owner_addressesstring[]

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

max 50 éléments
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

Valeurs autorisées :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 éléments
Réponses
201

Inbox created

objectstringrequis
Valeurs autorisées :inbox
idstring<uuid>requis
namestringrequis
email_addressstringrequis
domain_idstring<uuid>requis

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

receiving_addressstring | nullrequis
from_namestring | nullrequis
unreadintegerrequis

Threads with an unread message

draftsintegerrequis

Unsent drafts

last_receivedstring | nullrequis
created_atstringrequis
updated_atstringrequis
kindstringrequis
Valeurs autorisées :agenthuman
sharedbooleanrequis

On the shared inbox domain

expires_atstring | nullrequis
quarantinedintegerrequis

Held messages not yet released

pending_approvalintegerrequis

Drafts waiting for a person

401

Missing, malformed, unknown or revoked API key

statusCodenumberrequis
namestringrequis
messagestringrequis
403

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

statusCodenumberrequis
namestringrequis
messagestringrequis
409

The address is already used by an inbox

statusCodenumberrequis
namestringrequis
messagestringrequis
422

Validation error

statusCodenumberrequis
namestringrequis
messagestringrequis
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)

statusCodenumberrequis
namestringrequis
messagestringrequis
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

statusCodenumberrequis
namestringrequis
messagestringrequis
Essayer
Serveur
Autorisation
Corpsapplication/json
Requête
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"
    ]
  }
}'
Réponse
{
  "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
}

Cette page vous a-t-elle été utile ?