Sign inGet Started

Update the SMTP config for an API key

PATCH
/v1/email/smtp/configs/{api_key_id}
curl -X PATCH "https://us1.platform.bird.com/v1/email/smtp/configs/{api_key_id}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "marketing",
    "tags": [
      {
        "name": "category",
        "value": "welcome"
      }
    ]
  }'
Response200
{
  "api_key_id": "key_01krdgeqcxet5s7t44vh8rt9mg",
  "category": "marketing",
  "tags": [
    {
      "name": "category",
      "value": "welcome"
    }
  ],
  "created_at": "2026-05-20T09:14:52Z",
  "updated_at": "2026-05-25T16:42:01Z"
}

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.
  • Which Brand to send for.

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.

Parameters

api_key_idstring

ID of the API key the config applies to, the same key your SMTP client authenticates with.

Request Payload

ip_pool_id
nullable string

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
string

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.

Possible values: marketing, transactional

tags
array of object

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.

Show child parameters
track_opens
boolean

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

track_clicks
boolean

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

brand_id
nullable string

Select an active Brand in this workspace for messages submitted with this key. Send null to use the workspace default Brand, or omit to keep the current selection. An unavailable selection returns 422; a Brand whose setup is incomplete returns 503. When rotating an API key, configure the replacement key's Brand before switching SMTP traffic; the new key does not inherit these settings.

Response Payload

api_key_id
string
required

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
nullable string

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
string
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.

Possible values: marketing, transactional

tags
array of object
required

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.

Show child attributes
track_opens
boolean
required

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

track_clicks
boolean
required

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

created_at
string
required
updated_at
string
required
brand_id
nullable string

Brand selected for SMTP messages submitted with this key. null means messages use the workspace default Brand.