Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Bird Email Smtp Configs API
version: 1.0.0
description: 'The Bird API: one REST API for email, SMS, WhatsApp, verification, and
Realtime.'
servers:
- url: https://{region}.platform.bird.com
description: 'Regional API endpoint. Use the host for the region your organization is hosted in. Official Bird SDKs and the CLI select it automatically from your API key, so you rarely need to set it by hand.
'
variables:
region:
default: us1
enum:
- us1
- eu1
description: The region your organization's data is hosted in.
- url: https://platform.bird.com
description: Region-independent endpoint for authentication and account administration.
- url: http://localhost:8080
description: Local development.
security:
- BearerAuth: []
tags:
- name: email-smtp-configs
description: Default IP pool, category, tags, and open and click tracking settings for messages submitted over SMTP with a given API key.
paths:
/v1/email/smtp/configs:
get:
operationId: listEmailSmtpConfigs
summary: List SMTP configs
description: Returns the SMTP send-option configs stored for API keys in this workspace, as a cursor page. Only keys with an explicitly stored config are included. A key with no config still accepts SMTP submissions, using your organization's default pool, the transactional category, and tracking on.
tags:
- email-smtp-configs
security:
- BearerAuth: []
- CookieAuth: []
x-audiences:
- public
parameters:
- name: sort
in: query
required: false
description: Sort by `created_at`, the default and only supported field.
schema:
type: string
enum:
- created_at
default: created_at
- $ref: '#/components/parameters/OrderDesc'
- $ref: '#/components/parameters/PaginationLimit'
- $ref: '#/components/parameters/StartingAfter'
- $ref: '#/components/parameters/EndingBefore'
- $ref: '#/components/parameters/IncludeTotal'
responses:
'200':
description: Paginated list of SMTP configs.
content:
application/json:
schema:
$ref: '#/components/schemas/EmailSmtpConfigList'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'422':
$ref: '#/components/responses/Unprocessable'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/InternalError'
x-surfaces:
- n8n
/v1/email/smtp/configs/{api_key_id}:
parameters:
- name: api_key_id
in: path
required: true
description: 'ID of the API key the config applies to, the same key your SMTP client authenticates with.
'
schema:
$ref: '#/components/schemas/APIKeyID'
example: key_01krdgeqcxet5s7t44vh8rt9mg
get:
operationId: getEmailSmtpConfig
summary: Get an SMTP config
description: Returns the SMTP send-option config stored for the given API key. Returns a `404` if you have not set a config for that key. The key still accepts SMTP submissions, using your organization's default pool, the transactional category, and tracking on.
tags:
- email-smtp-configs
security:
- BearerAuth: []
- CookieAuth: []
x-audiences:
- public
responses:
'200':
description: SMTP config object.
content:
application/json:
schema:
$ref: '#/components/schemas/EmailSmtpConfig'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/Unprocessable'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/InternalError'
x-surfaces:
- n8n
patch:
operationId: updateEmailSmtpConfig
summary: Update the SMTP config for an API key
description: 'Sets the default send options applied to messages submitted over SMTP with this API key:
- Which IP pool to send from.
- The content category.
- Tags.
- Open and click tracking.
SMTP submissions have no fields for these, so Bird stores them per key instead.
A field you omit is left unchanged. If no config exists yet for this key, it is created first with the documented defaults (your organization''s default pool, transactional category, no tags, tracking on), and omitted fields take those defaults. A key that does not belong to this workspace returns `404`.'
tags:
- email-smtp-configs
security:
- BearerAuth: []
- CookieAuth: []
x-audiences:
- public
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EmailSmtpConfigUpdate'
responses:
'200':
description: The stored SMTP config.
headers:
Idempotency-Replay:
$ref: '#/components/headers/IdempotencyReplay'
content:
application/json:
schema:
$ref: '#/components/schemas/EmailSmtpConfig'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/Unprocessable'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/InternalError'
'503':
$ref: '#/components/responses/ServiceUnavailable'
x-surfaces:
- n8n
components:
parameters:
PaginationLimit:
name: limit
in: query
required: false
description: Maximum number of items to return per page.
schema:
type: integer
minimum: 1
maximum: 100
default: 25
IncludeTotal:
name: include_total
in: query
required: false
description: When true, the response includes a `total` field with the total number of items matching the request's filters across all pages.
schema:
type: boolean
default: false
IdempotencyKey:
name: Idempotency-Key
in: header
required: false
description: "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `<event-type>/<entity-id>` (for example `welcome-user/usr_abc123`).\n"
schema:
type: string
maxLength: 255
StartingAfter:
name: starting_after
in: query
required: false
description: Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order.
schema:
type: string
EndingBefore:
name: ending_before
in: query
required: false
description: Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since.
schema:
type: string
OrderDesc:
name: order
in: query
required: false
description: 'Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field.
'
schema:
$ref: '#/components/schemas/SortOrder'
default: desc
schemas:
ErrorBody:
type: object
additionalProperties: false
required:
- type
- code
- name
- message
- doc_url
- request_id
properties:
type:
type: string
minLength: 1
description: Broad category for coarse client branching.
enum:
- auth_error
- bad_request_error
- billing_error
- conflict_error
- gone_error
- internal_error
- misdirected_error
- not_found_error
- not_implemented_error
- payload_too_large_error
- permission_error
- precondition_error
- rate_limit_error
- service_unavailable_error
- too_early_error
- validation_error
code:
type: string
minLength: 1
pattern: ^E\d{5}$
description: Opaque, stable, unique error identifier. Never reused.
name:
type: string
minLength: 1
description: Human-readable slug for log readability. Paired with code, never replaces it.
message:
type: string
minLength: 1
description: Human-readable description. Not stable; clients must not parse it.
param:
type: string
minLength: 1
description: Identifies the offending field. Omitted when not applicable.
doc_url:
type: string
minLength: 1
format: uri
description: Stable link to the docs page for this error code.
request_id:
type: string
minLength: 1
description: Request correlation ID for support and troubleshooting. Also returned in the `X-Request-Id` response header.
vendor_code:
type: string
minLength: 1
description: 'Verbatim error code from an external system, such as an SMTP response code or a payment decline code. Present only when the code may help you resolve the error.
'
details:
type: array
description: Per-field validation errors. Present only on validation_error responses.
items:
$ref: '#/components/schemas/ErrorDetail'
remediation:
type: string
minLength: 1
description: A human-readable next step to resolve this error. Present when a recovery is known.
next:
type: array
description: 'The steps that resolve this error. Perform them in order, re-reading after each; a `wait` or `terminal` step is always last. Present for errors with a well-defined recovery, such as unmet preconditions and conflicts.
'
items:
$ref: '#/components/schemas/NextAction'
EmailSmtpConfig:
allOf:
- type: object
required:
- api_key_id
- category
- tags
- track_opens
- track_clicks
properties:
api_key_id:
readOnly: true
$ref: '#/components/schemas/APIKeyID'
description: 'ID of the API key this config applies to, the same key your SMTP client authenticates with. One config exists per key.
'
ip_pool_id:
type:
- string
- 'null'
pattern: ^ipp_([0-9a-hjkmnp-tv-z]{26}|shared)$
description: 'ID of the IP pool that SMTP sends with this key use, or `ipp_shared` for the shared pool. `null` when this key uses your organization''s default pool.
'
category:
type: string
minLength: 1
enum:
- marketing
- transactional
description: 'Content classification applied to messages submitted over SMTP with
this key. Controls suppression policy:
- `marketing`: Blocks on all suppression reasons.
- `transactional`: Allows delivery through complaint and unsubscribe suppressions.
'
tags:
type: array
items:
$ref: '#/components/schemas/Tag'
maxItems: 20
description: 'Structured `{name, value}` labels applied to every message submitted over SMTP with this key, the same tags used by the email sending API. Use tags to filter and break down your email statistics.
'
track_opens:
type: boolean
description: Whether open events are tracked for messages submitted over SMTP with this key.
track_clicks:
type: boolean
description: Whether click events are tracked for messages submitted over SMTP with this key.
- $ref: '#/components/schemas/Timestamps'
APIKeyID:
type: string
minLength: 1
pattern: ^key_[0-9a-hjkmnp-tv-z]{26}$
example: key_01krdgeqcxet5s7t44vh8rt9mg
_ListEnvelopeWithTotal:
allOf:
- $ref: '#/components/schemas/_ListEnvelope'
- type: object
properties:
total:
type:
- integer
- 'null'
format: int64
minimum: 0
description: Total number of items matching the request's filters across all pages. Present only when `include_total=true` was passed; otherwise `null`.
_ListEnvelope:
type: object
required:
- next_cursor
- prev_cursor
- refresh_cursor
properties:
next_cursor:
type:
- string
- 'null'
description: Cursor for the next page. Pass back as `starting_after` to advance forward. `null` when no next page exists.
example: eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9
prev_cursor:
type:
- string
- 'null'
description: Cursor for the previous page. Pass back as `ending_before` to step backward. `null` when no previous page exists.
example: null
refresh_cursor:
type:
- string
- 'null'
description: Refresh anchor, the first row of this response. Pass back as `ending_before` to fetch what precedes it in the current sort order. On a newest-first sort those are the items that have appeared since; on any other sort they are the items that sort earlier, so refreshing such a list means re-fetching it instead. Non-`null` whenever `data` is non-empty; `null` only on an empty page. Distinct from `prev_cursor`.
example: eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9
Timestamps:
type: object
required:
- created_at
- updated_at
properties:
created_at:
type: string
format: date-time
minLength: 1
readOnly: true
example: '2026-05-20T09:14:52Z'
updated_at:
type: string
format: date-time
minLength: 1
readOnly: true
example: '2026-05-25T16:42:01Z'
ErrorDetail:
type: object
additionalProperties: false
required:
- param
- message
properties:
param:
type: string
minLength: 1
description: 'Dotted field path, such as `to[0].email`, `subject`, or `.`. When the request was rejected for a query parameter the endpoint does not declare, this carries that parameter''s name instead of a field path.
'
message:
type: string
minLength: 1
description: What is wrong with this field.
EmailSmtpConfigList:
allOf:
- type: object
required:
- data
properties:
data:
type: array
description: Page of stored SMTP configs, newest first by default.
items:
$ref: '#/components/schemas/EmailSmtpConfig'
- $ref: '#/components/schemas/_ListEnvelopeWithTotal'
Tag:
type: object
additionalProperties: false
required:
- name
- value
description: 'Structured key/value label attached to a message or a call. Use tags for low-cardinality filtering dimensions (category, experiment ID, template ID); they surface in the list filter of whatever carries them.
On a message they also surface in the event log and in webhook payloads, and a message can carry `metadata` beside them for arbitrary per-send context that does not need to be filterable. A call has none of those three: its tags are set on the wire when the call is placed, and the call record is the one place you read them back.
Whatever carries the tags defines how many it may have. Tag names are unique: a send that repeats one is rejected, and on a call the first instance of a name wins.
'
properties:
name:
type: string
minLength: 1
maxLength: 32
pattern: ^[A-Za-z0-9_-]+$
description: 'Tag name. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 32 characters.
'
example: category
value:
type: string
minLength: 1
maxLength: 64
pattern: ^[A-Za-z0-9_-]+$
description: 'Tag value. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 64 characters.
'
example: welcome
NextAction:
type: object
additionalProperties: false
required:
- kind
- description
properties:
kind:
type: string
minLength: 1
x-extensible-enum:
- operation
- external
- wait
- terminal
description: "What you do about this step.\n\n- `operation`: call the operation named in `operation`, then\n read again.\n- `external`: act somewhere this API does not reach, then read\n again.\n- `wait`: nothing is asked of you, so read again later.\n- `terminal`: nothing you do resolves this, so stop retrying.\n\nTolerate a value you do not recognize: show the `description` and\noffer no action.\n"
description:
type: string
minLength: 1
description: A short, human-readable label for the step, suitable for display.
operation:
type: string
minLength: 1
description: 'The operationId to call. Present only when `kind` is `operation`. The operation''s own schema says how to call it; this says only which one, and what to address it with.
'
params:
type: object
additionalProperties:
type: string
minLength: 1
description: 'The parameters that address the operation, by name: `{"sender_id": "…"}` for an operation on `/v1/sms/senders/{sender_id}/requirements`. A parameter the operation takes in its query string is given the same way, so an operation addressed as `?subject_id=` carries `{"subject_id": "…"}`. Every parameter the call needs is here, whether its value came from the thing you were acting on or is fixed for this step, so you can make the call from this object alone. Present only when `kind` is `operation` and the operation names a subject. A request body, when the operation takes one, is described by the operation''s own schema and never appears here.
'
url:
type: string
format: uri
description: 'A URL to open. Present only when `kind` is `external`, and only when the step has one. An external step whose `description` says to go and do something with no URL to open is normal.
'
Error:
type: object
additionalProperties: false
required:
- error
properties:
error:
$ref: '#/components/schemas/ErrorBody'
SortOrder:
type: string
enum:
- asc
- desc
description: Sort direction, ascending or descending.
EmailSmtpConfigUpdate:
type: object
additionalProperties: false
description: 'Desired changes to the SMTP config for the key. A field you omit is left unchanged. If no config exists yet for this key, omitted fields take their documented defaults instead.
'
properties:
ip_pool_id:
type:
- string
- 'null'
pattern: ^ipp_([0-9a-hjkmnp-tv-z]{26}|shared)$
description: 'ID of the IP pool to send from (`ipp_` prefix), or `ipp_shared` to route through the shared pool explicitly. Send `null` to reset to your organization''s default pool, or omit to leave unchanged. An unknown pool, or a pool with no dedicated IPs available to send from, is rejected with a `422`.
'
category:
type: string
enum:
- marketing
- transactional
description: 'Content classification, independent of which endpoint messages are
submitted through. Controls suppression policy:
- `marketing`: Blocks on all suppression reasons.
- `transactional`: Allows delivery through complaint and unsubscribe suppressions.
Omit to leave unchanged.
'
tags:
type: array
items:
$ref: '#/components/schemas/Tag'
maxItems: 20
description: 'Structured `{name, value}` labels applied to every message submitted over SMTP with this key. Send an empty array to clear all tags, or omit to leave unchanged.
'
track_opens:
type: boolean
description: Whether to track open events for messages submitted over SMTP with this key. Omit to leave unchanged.
track_clicks:
type: boolean
description: Whether to track click events for messages submitted over SMTP with this key. Omit to leave unchanged.
responses:
InternalError:
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
RateLimited:
description: Rate limit exceeded
headers:
RateLimit:
$ref: '#/components/headers/RateLimit'
RateLimit-Policy:
$ref: '#/components/headers/RateLimit-Policy'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Forbidden:
description: Insufficient permissions
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
ServiceUnavailable:
description: 'The service is temporarily unavailable. If `Retry-After` is present, wait for that delay before retrying; otherwise, retry with exponential backoff. Reuse the same idempotency key and request when retrying a mutation.
'
headers:
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unprocessable:
description: 'The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`.
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
BadRequest:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Authentication required
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
headers:
RetryAfter:
description: 'Number of seconds to wait before retrying the request.
'
schema:
type: integer
minimum: 0
example: 35
IdempotencyReplay:
description: The API includes this header when it replays the response for an earlier request that used the same `Idempotency-Key`. The API does not process the request again.
schema:
type: string
enum:
- 'true'
RateLimit:
description: 'Remaining capacity for the request''s rate-limit policy as an IETF Structured Field. Format: `"<policy>";r=<remaining>;t=<seconds_until_reset>`.
'
schema:
type: string
example: '"email_send";r=842;t=35'
RateLimit-Policy:
description: 'Effective quota for the request''s rate-limit policy as an IETF Structured Field. Format: `"<policy>";q=<quota>;w=<window_seconds>`.
'
schema:
type: string
example: '"email_send";q=1000;w=60'
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 'Pass the API key as a bearer token in the `Authorization` header. Keys use
the format `bk_{region}_*`. The prefix identifies the region and selects the
API endpoint. Official Bird SDKs and the CLI derive the region from the key.
'
CookieAuth:
type: apiKey
in: cookie
name: bird_session
description: 'Session cookie set after signing in to the Bird dashboard. The cookie
value is an opaque session token; no session data is stored in the cookie
itself.
'
RealtimeKey:
type: apiKey
in: header
name: X-Realtime-Key
description: 'The Realtime app key. Together with `X-Realtime-Secret`, it authenticates a
request to the Realtime API in addition to the workspace credential. Both
values come from the app''s credentials and must belong to the calling
workspace. Official Bird SDKs accept the pair as client configuration.
'
RealtimeSecret:
type: apiKey
in: header
name: X-Realtime-Secret
description: 'The Realtime app secret paired with `X-Realtime-Key`. The API returns the
secret only when the key is created and does not store it. Create a new key
and revoke the current key if you lose the secret. Official Bird SDKs accept
the pair as client configuration.
'