---
title: "Update the SMTP config for an API key"
method: PATCH
path: "/v1/email/smtp/configs/{api_key_id}"
tags: ["email-smtp-configs"]
---

# Update the SMTP config for an API key

`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`

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

## Headers

- `Idempotency-Key` string
- `X-Workspace-Id` string
- `X-Organization-Id` string

## Request body

- EmailSmtpConfigUpdate: 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.
  - `ip_pool_id` string, 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.
  - `tags` Tag[]: 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.
    - `name` string, required: Tag name. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 32 characters.
    - `value` string, required: Tag value. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 64 characters.
  - `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.

## Response `200`

The stored SMTP config.

- EmailSmtpConfig
  - `api_key_id` string, required
  - `ip_pool_id` string, 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.
  - `tags` Tag[], 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.
    - `name` string, required: Tag name. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 32 characters.
    - `value` string, required: Tag value. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 64 characters.
  - `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, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `403`: Insufficient permissions
- `404`: Resource not found
- `422`: 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`.
- `429`: Rate limit exceeded
- `500`: Internal server error
- `503`: 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.

---

[API](https://skmtc.dev/messagebird/apis/bird-api.md) · [All operations](https://skmtc.dev/messagebird/apis/bird-api/llms.txt) · [OpenAPI document](https://skmtc.dev/messagebird/apis/bird-api/revisions/6dfce1179799?raw)