Method DeliverOutbound

internal/agent/api.go:1126–1224

DeliverOutbound is the shared send/reply/forward delivery tail, HTTP-free: HITL hold (HoldForApprovalCore), else self-send loopback, else SES send + record outbound + publish sent event. The caller has already authed, resolved + ownership-checked the agent, rate-limited, domain-verified, run the mes

(ctx context.Context, user *identity.User, agent *identity.AgentIdentity, req outbound.SendRequest, msgType, replyToEmailMessageID string, referenced *identity.Message)

// extraction). On a nil-error return the side effect has committed, so the
// idempotency key must be Completed (cached), never Released.
func (a *API) DeliverOutbound(ctx context.Context, user *identity.User, agent *identity.AgentIdentity, req outbound.SendRequest, msgType, replyToEmailMessageID string, referenced *identity.Message) (*OutboundResult, *OutboundError) {
	// Suppression enforcement (decision 9 / Slice 4b): fail fast if any
	// recipient is on this tenant's suppression list. Enforced fresh on every
	// attempt and NOT cached under the idempotency key (it's a clearable state,
	// released like every other error).
	if supErr := a.checkSuppression(ctx, user.ID, req); supErr != nil {
		return nil, supErr
	}

	// Outbound screening (Slice 5): the recipient gate (outbound_policy) + content
	// scan (outbound_scan) combine into one applied action. block ⇒ refuse;
	// review ⇒ hold; flag ⇒ send + annotate; allow ⇒ send.
	verdict := a.screenOutbound(ctx, agent, req)
	if verdict.Block() {
		// Egress block: refuse to the caller. No message row is persisted; the
		// audit lives in protection_events keyed to a STABLE soft-ref id so a
		// retried block doesn't write duplicate audit rows / events.
		a.auditRowless(ctx, agent, blockAuditID(agent.ID, req), req, verdict)
		a.emitBlockedOutbound(agent, blockAuditID(agent.ID, req), req, verdict)
		return nil, &OutboundError{http.StatusForbidden, "blocked_by_policy", "message blocked by outbound policy"}
	}

	// Hold when outbound screening says review. The outbound recipient gate
	// (outbound_policy: allowlist+review is the trust-ramp) + content scan now
	// fully own the hold decision — hitl_enabled/hitl_mode were retired in
	// Slice 5b (their behavior is mapped forward by migration 042).
	if verdict.Review() {
		msg, err := a.HoldForApprovalCore(ctx, agent, req, msgType, replyToEmailMessageID)
		if err != nil {
			if errors.Is(err, errHoldAttachments) {
				return nil, &OutboundError{http.StatusInternalServerError, "internal_error", "failed to serialize attachments"}
			}
			return nil, &OutboundError{http.StatusInternalServerError, "internal_error", "failed to hold message for approval"}
		}
		// Tag the held row + audit only when screening drove the hold (a pure
		// legacy-HITL hold carries no screening verdict).
		if verdict.Annotate() {
			a.annotateAndAudit(ctx, agent, msg.ID, req, verdict)
		}
		return &OutboundResult{Held: true, PendingMessageID: msg.ID, ApprovalExpiresAt: msg.ApprovalExpiresAt}, nil
	}

	// Record usage (side-effect only — never block on quota; the cap
	// pre-check is the gate).
	if _, err := a.usage.RecordAndCheck(ctx, user.ID, agent.ID, agent.Domain, "outbound"); err != nil {
		log.Printf("[api] usage recording error: %v", err)
	}

	if isSelfSend(req, agent.EmailAddress()) {
		providerID, err := a.performSelfSend(ctx, agent, req, msgType)
		if err != nil {
			log.Printf("[api] self-send failed: agent=%s error=%v", agent.EmailAddress(), err)
			return nil, &OutboundError{http.StatusInternalServerError, "internal_error", "self-send failed"}
		}
		slug, _, _ := strings.Cut(agent.EmailAddress(), "@")
		log.Printf("[mail] dir=outbound type=%s method=loopback from=%s to=%s slug=%s conv_id=%s subject=%q provider_id=%s", msgType, agent.EmailAddress(), agent.EmailAddress(), slug, req.ConversationID, req.Subject, providerID)
		return &OutboundResult{MessageID: providerID, Method: "loopback"}, nil
	}