Postbox docs

Read your org profile, track plan usage against your limits, and query the outbound delivery log.

Beyond sending and receiving, the API exposes your org's own state: the account profile, current usage against your plan, and a queryable log of every outbound send. These are org-level reads (they don't need X-Project-Id), except the outbound log, which you can narrow to one project.

Account

Read or update the org profile. Only the name and billing email are editable here; plan and status are managed through billing.

import { Postbox } from "@postbox/sdk";

const pb = new Postbox({
  apiKey: process.env.PB_KEY!,
  projectId: process.env.PROJECT_ID!,
});

await pb.account.get();

await pb.account.update({ billingEmail: "[email protected]" });

import os
from postbox import Postbox

pb = Postbox(api_key=os.environ["PB_KEY"], project_id=os.environ["PROJECT_ID"])

pb.account.get()

pb.account.update({"billingEmail": "[email protected]"})

using Postbox;

var pb = new PostboxClient(
    new PostboxOptions
    {
        ApiKey = Environment.GetEnvironmentVariable("PB_KEY")!,
        ProjectId = Environment.GetEnvironmentVariable("PROJECT_ID")!,
    }
);

await pb.Account.GetAsync();

await pb.Account.UpdateAsync(new AccountUpdateBody { BillingEmail = "[email protected]" });

import cloud.postboxapp.*;
import cloud.postboxapp.gen.*;
import java.util.*;

Postbox pb = new Postbox(PostboxOptions.builder().apiKey(System.getenv("PB_KEY")).projectId(System.getenv("PROJECT_ID")).build());

pb.account.get();

pb.account.update(AccountUpdateBody.builder().billingEmail("[email protected]").build());

import postbox "github.com/postboxapp/postbox-go"

pb, err := postbox.New(postbox.Options{APIKey: os.Getenv("PB_KEY"), ProjectID: os.Getenv("PROJECT_ID")})
ctx := context.Background()

pb.Account.Get(ctx)

pb.Account.Update(ctx, &postbox.AccountUpdateBody{BillingEmail: "[email protected]"})

curl https://api.postboxapp.cloud/v1/account \
  -H "Authorization: Bearer $PB_KEY"

curl -X PATCH https://api.postboxapp.cloud/v1/account \
  -H "Authorization: Bearer $PB_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Inc", "billingEmail": "[email protected]" }'

The response carries plan, status, billingActive, region, and onboardedAt alongside name and billingEmail.

Usage

Usage reports what you have consumed this billing period against your plan's limits. Use it to show a usage bar, or to alert before you hit an overage.

const usage = await pb.stats.usage();

usage = pb.stats.usage()

var usage = await pb.Stats.UsageAsync();

var usage = pb.stats.usage();

usage, err := pb.Stats.Usage(ctx)

curl https://api.postboxapp.cloud/v1/stats/usage \
  -H "Authorization: Bearer $PB_KEY"

{
  "success": true,
  "data": {
    "plan": { "slug": "scale", "name": "Scale", "billingActive": true },
    "limits": {
      "mailboxes": 500,
      "emailsIncluded": 100000,
      "storageGb": 50,
      "overagePer1kUsd": 0.5
    },
    "usage": {
      "emailsThisPeriod": 41230,
      "mailboxes": 128,
      "storageGb": 12.4
    }
  }
}

A null in limits means that dimension is unlimited on your plan. overagePer1kUsd is what each additional 1,000 emails costs once emailsIncluded is used up.

Outbound log

Every send lands in the outbound log with its full delivery detail: provider message id, attempt count, SMTP response, and bounce classification. This is the pull-based audit trail, the counterpart to the push-based webhooks and events.

const log = await pb.logs.outbound();

for (const row of log.items) {
  console.log(row.toAddress, row.status, row.bounceType);
}

log = pb.logs.outbound()

for row in log["items"]:
    print(row["toAddress"], row["status"], row["bounceType"])

var log = await pb.Logs.OutboundAsync();

foreach (var row in log!.Items!)
{
    Console.WriteLine($"{row.ToAddress} {row.Status} {row.BounceType}");
}

var log = pb.logs.outbound();

for (var row : log.items()) {
    System.out.println(row.toAddress() + " " + row.status() + " " + row.bounceType());
}

log, err := pb.Logs.Outbound(ctx)

for _, row := range log.Items {
    fmt.Println(row.ToAddress, row.Status, row.BounceType)
}

curl "https://api.postboxapp.cloud/v1/logs/outbound?page=1&pageSize=50" \
  -H "Authorization: Bearer $PB_KEY" -H "X-Project-Id: $PROJECT_ID"

The response is paginated (items, total, page, pageSize, totalPages). Pass X-Project-Id to scope the log to one project; omit it to see the whole org. Each row includes:

Field	Notes
`status`	Where the send is in its lifecycle (see Sending).
`providerMessageId`	The SES message id, for correlating with provider-side records.
`attempts`, `nextRetryAt`	Retry state for a deferred send.
`smtpResponse`	The raw response from the receiving server.
`bounceType`, `bounceCode`	`hard` or `soft`, plus the code, when it bounced.

To check one message rather than scan the log, poll its status directly (see Sending).

Account & usage

Account

Usage

Outbound log

On this page