---
title: "Start secure email delivery connection setup"
method: POST
path: "/v1/email-delivery-connection-setup-sessions"
tags: ["Email Delivery Connections"]
---

# Start secure email delivery connection setup

`POST /v1/email-delivery-connection-setup-sessions`

## Request

- Base URL: `https://api.mailrith.com`
- URL: `https://api.mailrith.com/v1/email-delivery-connection-setup-sessions`
- Auth: HTTP bearer

Creates a short-lived browser handoff containing only non-secret defaults. Open setup_url so an authorized Mailrith user can enter provider credentials directly in Mailrith.

## Request body

- EmailDeliveryConnectionSetupRequest: Non-secret defaults for a short-lived setup session. For create, include name, provider, from_email, and from_name. For replace_credentials, include connection_id. Provider credentials must never be sent to this API.
  - `purpose` 'create' | 'replace_credentials'
  - `connection_id` string: Required only when purpose is replace_credentials.
  - `name` string
  - `provider` 'amazon-ses' | 'postmark' | 'sendgrid' | 'mailgun' | 'resend' | 'brevo' | 'custom-smtp'
  - `from_email` string, email
  - `from_name` string

## Response `201`

Secure setup session created

- object
  - `data` EmailDeliveryConnectionSetupSession, required
    - `self` string, required: Stable relative Public API path for retrieving this resource.
    - `id` string, required
    - `purpose` 'create' | 'replace_credentials', required
    - `status` 'pending' | 'completed' | 'failed' | 'expired', required
    - `setup_url` string, uri: Returned only when the session is created. Open this short-lived link in a browser to enter provider credentials directly in Mailrith.
    - `connection_id` string, nullable
    - `expires_at` string, date-time, required
    - `completed_at` string, date-time, nullable
    - `failed_at` string, date-time, nullable
    - `failure_code` 'setup_action_failed' | 'null', nullable: Generic failure code. Provider error details and credentials are never stored in the session.

## Other responses

- `400`: The non-secret setup defaults are invalid.

---

[API](https://skmtc.dev/mailrith/apis/mailrith-api.md) · [All operations](https://skmtc.dev/mailrith/apis/mailrith-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mailrith/apis/mailrith-api/revisions/41f09536f2da?raw)