Skip to content
builders.ac

Deliverability API · Alpha / unstable

Retrieve bounce totals, trends, and per-domain rates

GET
/bounces
curl --request GET \
  --url 'https://api.builders.ac/api/deliverability/v1alpha1/bounces?range=1h' \
  --header 'Authorization: Bearer <token>'

This aggregate resource intentionally omits mailbox-level event payloads; individual events belong to the Mailbox Events API.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
range
string
default: 7d
Allowed values: 1h 8h 24h 3d 7d 14d

Time window. Defaults to 7d.

sender_id
string
/^snd_[0-9a-z]{26}$/

Restrict data to one sender owned by the authenticated account.

domain_id
string
/^dom_[0-9a-z]{26}$/

Restrict data to one domain owned by the authenticated account.

Responses

Section titled “Responses”

200

Section titled “200”

Bounce analytics

Media typeapplication/json
object
totals
required
object
hard
required
integer
soft
required
integer
pending
required
integer
sent
required
integer
rate_unavailable
required
string | null
by_esp
required
object
microsoft
required
integer
google
required
integer
others
required
integer
trend
required
Array<object>
object
day
required
string
date
string format: date
microsoft
required
integer
google
required
integer
others
required
integer
by_domain
required
Array<object>
object
domain_id
required
string
/^dom_[0-9a-z]{26}$/
name
required
string
sent
required
integer
bounces
required
integer
hard_bounces
required
integer
soft_bounces
required
integer
pending_bounces
required
integer
sent_incomplete
required
boolean
rate_unavailable
required
string | null
rate
required
number | null
Examplegenerated
{
  "totals": {
    "hard": 1,
    "soft": 1,
    "pending": 1,
    "sent": 1,
    "rate_unavailable": "example"
  },
  "by_esp": {
    "microsoft": 1,
    "google": 1,
    "others": 1
  },
  "trend": [
    {
      "day": "example",
      "date": "2026-04-15",
      "microsoft": 1,
      "google": 1,
      "others": 1
    }
  ],
  "by_domain": [
    {
      "domain_id": "example",
      "name": "example",
      "sent": 1,
      "bounces": 1,
      "hard_bounces": 1,
      "soft_bounces": 1,
      "pending_bounces": 1,
      "sent_incomplete": true,
      "rate_unavailable": "example",
      "rate": 1
    }
  ]
}

401

Section titled “401”

RFC 9457 problem details

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
>= 400 <= 599
detail
required
string
code
required
string
retryable
required
boolean
correlation_id
required
string
retry_after
string format: date-time
errors
object
key
additional properties
Array<string>
key
additional properties
any
Examplegenerated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "code": "example",
  "retryable": true,
  "correlation_id": "example",
  "retry_after": "2026-04-15T12:00:00Z",
  "errors": {
    "additionalProperty": [
      "example"
    ]
  }
}

403

Section titled “403”

RFC 9457 problem details

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
>= 400 <= 599
detail
required
string
code
required
string
retryable
required
boolean
correlation_id
required
string
retry_after
string format: date-time
errors
object
key
additional properties
Array<string>
key
additional properties
any
Examplegenerated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "code": "example",
  "retryable": true,
  "correlation_id": "example",
  "retry_after": "2026-04-15T12:00:00Z",
  "errors": {
    "additionalProperty": [
      "example"
    ]
  }
}

404

Section titled “404”

RFC 9457 problem details

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
>= 400 <= 599
detail
required
string
code
required
string
retryable
required
boolean
correlation_id
required
string
retry_after
string format: date-time
errors
object
key
additional properties
Array<string>
key
additional properties
any
Examplegenerated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "code": "example",
  "retryable": true,
  "correlation_id": "example",
  "retry_after": "2026-04-15T12:00:00Z",
  "errors": {
    "additionalProperty": [
      "example"
    ]
  }
}

422

Section titled “422”

RFC 9457 problem details

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
>= 400 <= 599
detail
required
string
code
required
string
retryable
required
boolean
correlation_id
required
string
retry_after
string format: date-time
errors
object
key
additional properties
Array<string>
key
additional properties
any
Examplegenerated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "code": "example",
  "retryable": true,
  "correlation_id": "example",
  "retry_after": "2026-04-15T12:00:00Z",
  "errors": {
    "additionalProperty": [
      "example"
    ]
  }
}

429

Section titled “429”

RFC 9457 problem details

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
>= 400 <= 599
detail
required
string
code
required
string
retryable
required
boolean
correlation_id
required
string
retry_after
string format: date-time
errors
object
key
additional properties
Array<string>
key
additional properties
any
Examplegenerated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "code": "example",
  "retryable": true,
  "correlation_id": "example",
  "retry_after": "2026-04-15T12:00:00Z",
  "errors": {
    "additionalProperty": [
      "example"
    ]
  }
}

500

Section titled “500”

RFC 9457 problem details

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
>= 400 <= 599
detail
required
string
code
required
string
retryable
required
boolean
correlation_id
required
string
retry_after
string format: date-time
errors
object
key
additional properties
Array<string>
key
additional properties
any
Examplegenerated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "code": "example",
  "retryable": true,
  "correlation_id": "example",
  "retry_after": "2026-04-15T12:00:00Z",
  "errors": {
    "additionalProperty": [
      "example"
    ]
  }
}

503

Section titled “503”

RFC 9457 problem details

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
>= 400 <= 599
detail
required
string
code
required
string
retryable
required
boolean
correlation_id
required
string
retry_after
string format: date-time
errors
object
key
additional properties
Array<string>
key
additional properties
any
Examplegenerated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "code": "example",
  "retryable": true,
  "correlation_id": "example",
  "retry_after": "2026-04-15T12:00:00Z",
  "errors": {
    "additionalProperty": [
      "example"
    ]
  }
}