feat(api): api update

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 21
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/cas-parser%2Fcas-parser-d868ff00b7b07f6b6802b00f22fad531a91a76bb219a634f3f90fe488bd499ba.yml
-openapi_spec_hash: 20e9f2fc31feee78878cdf56e46dab60
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/cas-parser%2Fcas-parser-78ef474b9e171a3eaa430a9dacdc2fa5c7f7d5f89147cb20573a355d3dbb9f0e.yml
+openapi_spec_hash: 11b6e43ef4ed724f9804c9d790a4faee
 config_hash: 5509bb7a961ae2e79114b24c381606d4

inboundemail.go

@@ -67,26 +67,14 @@ func NewInboundEmailService(opts ...option.RequestOption) (r InboundEmailService
 }
 
 // Create a dedicated inbound email address for collecting CAS statements via email
-// forwarding.
+// forwarding. When an investor forwards a CAS email to this address, we verify the
+// sender and make the file available to you.
 //
-// **How it works:**
-//
-//  1. Create an inbound email with your webhook URL
-//  2. Display the email address to your user (e.g., "Forward your CAS to
-//     ie_xxx@import.casparser.in")
-//  3. When an investor forwards a CAS email, we verify the sender and deliver to
-//     your webhook
-//
-// **Webhook Delivery:**
+// `callback_url` is **optional**:
 //
-//   - We POST to your `callback_url` with JSON body containing files (matching
-//     EmailCASFile schema)
-//   - Failed deliveries are retried automatically with exponential backoff
-//
-// **Inactivity:**
-//
-// - Inbound emails with no activity in 30 days are marked inactive
-// - Active inbound emails remain operational indefinitely
+//   - **Set it** — we POST each parsed email to your webhook as it arrives.
+//   - **Omit it** — retrieve files via `GET /v4/inbound-email/{id}/files` without
+//     building a webhook consumer.
 func (r *InboundEmailService) New(ctx context.Context, body InboundEmailNewParams, opts ...option.RequestOption) (res *InboundEmailNewResponse, err error) {
 	opts = slices.Concat(r.Options, opts)
 	path := "v4/inbound-email"
@@ -136,8 +124,9 @@ type InboundEmailNewResponse struct {
 	//
 	// Any of "cdsl", "nsdl", "cams", "kfintech".
 	AllowedSources []string `json:"allowed_sources"`
-	// Webhook URL for email notifications
-	CallbackURL string `json:"callback_url" format:"uri"`
+	// Webhook URL for email notifications. `null` means files are only retrievable via
+	// `GET /v4/inbound-email/{id}/files` (pull delivery).
+	CallbackURL string `json:"callback_url" api:"nullable" format:"uri"`
 	// When the mailbox was created
 	CreatedAt time.Time `json:"created_at" format:"date-time"`
 	// The inbound email address to forward CAS statements to
@@ -190,8 +179,9 @@ type InboundEmailGetResponse struct {
 	//
 	// Any of "cdsl", "nsdl", "cams", "kfintech".
 	AllowedSources []string `json:"allowed_sources"`
-	// Webhook URL for email notifications
-	CallbackURL string `json:"callback_url" format:"uri"`
+	// Webhook URL for email notifications. `null` means files are only retrievable via
+	// `GET /v4/inbound-email/{id}/files` (pull delivery).
+	CallbackURL string `json:"callback_url" api:"nullable" format:"uri"`
 	// When the mailbox was created
 	CreatedAt time.Time `json:"created_at" format:"date-time"`
 	// The inbound email address to forward CAS statements to
@@ -269,8 +259,9 @@ type InboundEmailListResponseInboundEmail struct {
 	//
 	// Any of "cdsl", "nsdl", "cams", "kfintech".
 	AllowedSources []string `json:"allowed_sources"`
-	// Webhook URL for email notifications
-	CallbackURL string `json:"callback_url" format:"uri"`
+	// Webhook URL for email notifications. `null` means files are only retrievable via
+	// `GET /v4/inbound-email/{id}/files` (pull delivery).
+	CallbackURL string `json:"callback_url" api:"nullable" format:"uri"`
 	// When the mailbox was created
 	CreatedAt time.Time `json:"created_at" format:"date-time"`
 	// The inbound email address to forward CAS statements to
@@ -328,16 +319,13 @@ func (r *InboundEmailDeleteResponse) UnmarshalJSON(data []byte) error {
 }
 
 type InboundEmailNewParams struct {
-	// Webhook URL where we POST email notifications. Must be HTTPS in production (HTTP
-	// allowed for localhost during development).
-	CallbackURL string `json:"callback_url" api:"required" format:"uri"`
-	// Optional custom email prefix for user-friendly addresses.
-	//
-	// - Must be 3-32 characters
-	// - Alphanumeric + hyphens only
-	// - Must start and end with letter/number
-	// - Example: `john-portfolio@import.casparser.in`
-	// - If omitted, generates random ID like `ie_abc123xyz@import.casparser.in`
+	// Optional webhook URL where we POST parsed emails. Must be HTTPS in production
+	// (HTTP allowed for localhost). If omitted, retrieve files via
+	// `GET /v4/inbound-email/{id}/files`.
+	CallbackURL param.Opt[string] `json:"callback_url,omitzero" format:"uri"`
+	// Optional custom email prefix (e.g. `john-portfolio@import.casparser.in`). 3-32
+	// chars, alphanumeric + hyphens, must start/end with a letter or number. If
+	// omitted, a random ID is generated.
 	Alias param.Opt[string] `json:"alias,omitzero"`
 	// Your internal identifier (e.g., user_id, account_id). Returned in webhook
 	// payload for correlation.

inboundemail_test.go

@@ -27,9 +27,9 @@ func TestInboundEmailNewWithOptionalParams(t *testing.T) {
 		option.WithAPIKey("My API Key"),
 	)
 	_, err := client.InboundEmail.New(context.TODO(), casparser.InboundEmailNewParams{
-		CallbackURL:    "https://api.yourapp.com/webhooks/cas-email",
 		Alias:          casparser.String("john-portfolio"),
 		AllowedSources: []string{"cdsl", "nsdl"},
+		CallbackURL:    casparser.String("https://api.yourapp.com/webhooks/cas-email"),
 		Metadata: map[string]string{
 			"plan":   "premium",
 			"source": "onboarding",