<Intro>

<EndpointHeader />

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

</Description>

</Intro>

<Parameters in="query">

<Parameter name="sort" type="string">

<Description>

Field to sort by.

</Description>

<Description>

Possible values: `created_at`

</Description>

</Parameter>

<Parameter name="order" type="string">

<Description>

Sort direction. Defaults to `desc` (newest/largest first).

</Description>

<Description>

Possible values: `asc`, `desc`

</Description>

</Parameter>

<Parameter name="limit" type="integer">

<Description>

Maximum number of items to return per page.

</Description>

</Parameter>

<Parameter name="starting_after" type="string">

<Description>

Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order.

</Description>

</Parameter>

<Parameter name="ending_before" type="string">

<Description>

Cursor from the `prev_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order.

</Description>

</Parameter>

<Parameter name="include_total" type="boolean">

<Description>

When true, the response includes a `total` field with the total number of items matching the request's filters across all pages.

</Description>

</Parameter>

</Parameters>

<Payload kind="response">

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

<Description>

Page of stored SMTP configs, newest first by default.

</Description>

<FieldChildren kind="response">

<Field name="api_key_id" type="string" prefix="data." 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" prefix="data.">

<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" prefix="data." 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" prefix="data." 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="data.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="data.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" prefix="data." required>

<Description>

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

</Description>

</Field>

<Field name="track_clicks" type="boolean" prefix="data." required>

<Description>

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

</Description>

</Field>

<Field name="created_at" type="string" prefix="data." required />

<Field name="updated_at" type="string" prefix="data." required />

</FieldChildren>

</Field>

<Field name="next_cursor" type="nullable string" required>

<Description>

Cursor for the next page. Pass back as `starting_after` to advance forward. Null when no next page exists.

</Description>

</Field>

<Field name="prev_cursor" type="nullable string" required>

<Description>

Cursor for the previous page. Pass back as `ending_before` to step backward. Null when no previous page exists.

</Description>

</Field>

<Field name="refresh_cursor" type="nullable string" required>

<Description>

Refresh anchor. Pass back as `ending_before` later to fetch items that have appeared since this response. Non-null whenever `data` is non-empty; null only on an empty page. Distinct from `prev_cursor`.

</Description>

</Field>

<Field name="total" type="nullable integer">

<Description>

Total number of items matching the request's filters across all pages. Present only when `include_total=true` was passed; otherwise null.

</Description>

</Field>

</Payload>