<Intro>

<EndpointHeader />

<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, and open/click tracking. SMTP submissions cannot carry these as
request fields, so they are stored 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`.

</Description>

</Intro>

<Payload kind="request">

<Field name="ip_pool_id" type="nullable string">

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

</Description>

</Field>

<Field name="category" type="string">

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

</Description>

<Description>

Possible values: `marketing`, `transactional`

</Description>

</Field>

<Field name="tags" type="array of object">

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

</Description>

<FieldChildren kind="request">

<Field name="name" type="string" prefix="tags." required>

<Description>

Tag name. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 32 characters.

</Description>

</Field>

<Field name="value" type="string" prefix="tags." required>

<Description>

Tag value. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 64 characters.

</Description>

</Field>

</FieldChildren>

</Field>

<Field name="track_opens" type="boolean">

<Description>

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

</Description>

</Field>

<Field name="track_clicks" type="boolean">

<Description>

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

</Description>

</Field>

</Payload>

<Payload kind="response">

<Field name="api_key_id" type="string" required>

<Description>

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

</Description>

</Field>

<Field name="ip_pool_id" type="nullable string">

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

</Description>

</Field>

<Field name="category" type="string" required>

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

</Description>

<Description>

Possible values: `marketing`, `transactional`

</Description>

</Field>

<Field name="tags" type="array of object" required>

<Description>

Structured `{name, value}` labels applied to every message submitted over SMTP with this key — the same tags used by the email sending API. See EmailMessageSendRequest for how tags are used for filtering and analytics.

</Description>

<FieldChildren kind="response">

<Field name="name" type="string" prefix="tags." required>

<Description>

Tag name. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 32 characters.

</Description>

</Field>

<Field name="value" type="string" prefix="tags." required>

<Description>

Tag value. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 64 characters.

</Description>

</Field>

</FieldChildren>

</Field>

<Field name="track_opens" type="boolean" required>

<Description>

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

</Description>

</Field>

<Field name="track_clicks" type="boolean" required>

<Description>

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

</Description>

</Field>

<Field name="created_at" type="string" required />

<Field name="updated_at" type="string" required />

</Payload>