email-smtp-configs

Update the SMTP config for an API key

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.

patch/v1/email/smtp/configs/{api_key_id}

Request

  • Base URL: https://us1.platform.bird.com
  • URL: https://us1.platform.bird.com/v1/email/smtp/configs/{api_key_id}
  • Auth: one of:
    • HTTP bearer
    • API key in cookie bird_session

Headers

Idempotency-Keystring

Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay.

On a supported operation, if idempotency protection is unavailable before execution, the API returns 503 IdempotencyUnavailable (E01033) without executing this attempt. Retry with backoff using the same key and request. An operation that takes effect before its response is retained can still execute again on retry.

Two distinct 409 errors signal misuse:

  • request_in_progress (E01004): The same key is currently being processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
  • idempotency_key_reuse (E01005): The same key has already completed against a different request body or method. Generate a new key.

Recommended key format is <event-type>/<entity-id> (for example welcome-user/usr_abc123).

X-Workspace-Idstring

Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.

X-Organization-Idstring

Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.

Request body

ip_pool_idstring nullable

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'marketing' | 'transactional'

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.

track_opensboolean

Whether to track open events for messages submitted over SMTP with this key. Omit to leave unchanged.

track_clicksboolean

Whether to track click events for messages submitted over SMTP with this key. Omit to leave unchanged.

Example request

{
  "tags": [
    {
      "name": "category",
      "value": "welcome"
    }
  ]
}

Response

The stored SMTP config.

api_key_idstring required
ip_pool_idstring nullable

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'marketing' | 'transactional' required

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.
track_opensboolean required

Whether open events are tracked for messages submitted over SMTP with this key.

track_clicksboolean required

Whether click events are tracked for messages submitted over SMTP with this key.

created_atstring date-time required
updated_atstring date-time required

Example response

{
  "api_key_id": "key_01krdgeqcxet5s7t44vh8rt9mg",
  "tags": [
    {
      "name": "category",
      "value": "welcome"
    }
  ],
  "created_at": "2026-05-20T09:14:52Z",
  "updated_at": "2026-05-25T16:42:01Z"
}

Changes

No recorded changes to this operation across all 2 revisions of this API.