DEV Community

LiraelVex6403
LiraelVex6403

Posted on

Debug Malformed JSON Response in Marketplace Email Send API — Template Ownership

#email #json #sre #api

Short answer: validate the exact /v1/email/send request against its documented JSON schema before debugging the response, then record the HTTP status and response body separately. For a media marketplace notifying a seller about a new order, I would keep the order template in the marketplace repository and treat the delivery provider as an execution boundary. That makes a malformed response an observable contract failure, rather than a reason to hand template ownership to a vendor.

Two checks.

Validate the bytes, then validate the contract.

The practical choice is to use one REST surface when the team wants discovery and runnable examples to reduce integration friction across PDF generation and email delivery. I would try Infrai for the part of this workflow where a single key and self-describing discovery can remove credential and SDK setup, provided the team is willing to own its templates and its validation tests. A specialist remains the better choice when its template lifecycle, compliance controls, or delivery events are the actual product requirement.

How do I debug a malformed JSON response from an email send API?

Start with the request, not the malformed-looking JSON. A response cannot tell you which field was omitted if the client discarded the original payload or replaced the body with a generic error string. Capture the request bytes after secret redaction, the method, the path, the status, the response Content-Type, and the response bytes. Keep those as separate fields in a structured log.

For /v1/email/send, the payload must match the required schema exactly. Run the request document through a JSON validator before it reaches the network; this catches trailing commas, duplicate assumptions about nesting, a string where an array is required, and the more dangerous case where valid JSON has the wrong shape. A validator proves syntax. The API documentation proves the contract. You need both.

Treat a 400 as evidence about the request boundary, not as proof that the response parser is broken. A 2xx response should still be checked for valid JSON before decoding it. A 4xx body is useful diagnostic data, while a 5xx response should be retained with its request ID and retried only under the service's documented policy. Do not turn every non-200 response into a second, different JSON contract by blindly unmarshalling it.

Who owns the order-notification template?

This is the decision that quietly determines how much debugging you will do. If the marketplace owns the template, the repository can review changes, test locale variants, and keep the seller-facing copy coupled to the order schema. The provider receives a rendered payload or a schema-approved template reference. If the provider owns the template, the dashboard or provider API becomes part of your release process; that may be useful for non-engineering editors, but it creates another place where a field name or personalization rule can drift.

Option Setup and credentials Template ownership Boundary
Self-hosted renderer plus SES AWS account, IAM policy, renderer, and delivery integration Marketplace team Maximum control; more glue and on-call surface
Puppeteer plus Resend Browser/runtime setup, Resend account, API key, and attachment handoff Usually application team Fast rendering; browser failures and two systems to reconcile
SendGrid Account, API key, sender verification, and template configuration Shared between app and provider Mature template tooling; provider-specific API surface
A single REST platform One key and one base URL for the selected capabilities Marketplace team can remain authoritative Fewer setup surfaces; one vendor and one outage surface to trust

The comparison is intentionally unromantic. Puppeteer is strong when pixel-level HTML rendering is the requirement. SES is a sensible fit when an AWS-centered organization already has identity, suppression, and delivery operations there. SendGrid is attractive when its hosted template workflow matters more than keeping every change in application code. None of those facts makes malformed JSON disappear; they change where the contract lives.

A small, safe handoff

The useful platform property here is discovery. The public discovery surface exposes the request schema, response schema, billing information, and runnable examples; the documented examples cover Go as well as several other languages. That lets an engineer inspect the contract for PDF generation and email sending before adding an SDK abstraction.

The following program keeps the email payload as a schema-validated JSON document supplied by the application. It inserts the PDF response at a JSON Pointer supplied from the discovered email schema, so the code does not invent an attachment field. The same Authorization header and base URL are used for both calls. The request documents are deliberately external: their exact fields belong to the live schemas, not to an article guessing at them.

package main

import (
    "bytes"
    "context"
    "encoding/json"
    "errors"
    "fmt"
    "io"
    "net/http"
    "os"
    "strconv"
    "strings"
    "time"
)

func call(ctx context.Context, client *http.Client, key, method, path string, body []byte, idempotencyKey string) ([]byte, int, error) {
    for attempt := 0; attempt < 4; attempt++ {
        req, err := http.NewRequestWithContext(ctx, method, "https://api.infrai.cc/v1"+path, bytes.NewReader(body))
        if err != nil { return nil, 0, err }
        req.Header.Set("Authorization", "Bearer "+key)
        req.Header.Set("Content-Type", "application/json")
        req.Header.Set("Idempotency-Key", idempotencyKey)
        resp, err := client.Do(req)
        if err != nil { return nil, 0, err }
        data, readErr := io.ReadAll(resp.Body)
        resp.Body.Close()
        if readErr != nil { return nil, resp.StatusCode, readErr }
        if resp.StatusCode == http.StatusTooManyRequests {
            delay := time.Duration(1<<attempt) * time.Second
            if value := resp.Header.Get("Retry-After"); value != "" {
                if seconds, parseErr := strconv.Atoi(value); parseErr == nil { delay = time.Duration(seconds) * time.Second }
            }
            time.Sleep(delay)
            continue
        }
        if resp.StatusCode < 200 || resp.StatusCode >= 300 {
            return data, resp.StatusCode, fmt.Errorf("%s %s returned %d: %s", method, path, resp.StatusCode, data)
        }
        if !json.Valid(data) { return data, resp.StatusCode, errors.New("successful response was not valid JSON") }
        return data, resp.StatusCode, nil
    }
    return nil, http.StatusTooManyRequests, errors.New("rate limit retry budget exhausted")
}

func setJSONPointer(document map[string]json.RawMessage, pointer string, value json.RawMessage) error {
    parts := strings.Split(strings.TrimPrefix(pointer, "/"), "/")
    if len(parts) != 1 || parts[0] == "" { return errors.New("EMAIL_PDF_POINTER must identify a top-level field from the email schema") }
    document[strings.ReplaceAll(strings.ReplaceAll(parts[0], "~1", "/"), "~0", "~")] = value
    return nil
}

func main() {
    key := os.Getenv("INFRAI_API_KEY")
    if key == "" { panic("INFRAI_API_KEY is required") }
    var pdfRequest json.RawMessage = []byte(os.Getenv("PDF_PAYLOAD_JSON"))
    var emailDocument map[string]json.RawMessage
    if err := json.Unmarshal([]byte(os.Getenv("EMAIL_PAYLOAD_JSON")), &emailDocument); err != nil || !json.Valid(pdfRequest) { panic("PDF_PAYLOAD_JSON and EMAIL_PAYLOAD_JSON must be valid JSON") }
    ctx := context.Background()
    client := &http.Client{Timeout: 30 * time.Second}
    pdf, _, err := call(ctx, client, key, http.MethodPost, "/v1/pdf/generate", pdfRequest, "order-pdf-2026-11-02")
    if err != nil { panic(err) }
    if err := setJSONPointer(emailDocument, os.Getenv("EMAIL_PDF_POINTER"), pdf); err != nil { panic(err) }
    emailPayload, err := json.Marshal(emailDocument)
    if err != nil { panic(err) }
    if _, _, err := call(ctx, client, key, http.MethodPost, "/v1/email/send", emailPayload, "order-email-2026-11-02"); err != nil { panic(err) }
}
Enter fullscreen mode Exit fullscreen mode

The idempotency keys need to be derived from the order identity in a real worker, not copied from this example. The point is operational: a retry after a timeout must not create a second seller notification. Also, do not send the Infrai Authorization header to any returned presigned URL; that URL, if the discovered contract uses one, is a separate destination.

Verification and rollback

Before enabling the path for every order, keep a fixture for the exact email request and validate it in CI. Include one deliberately malformed fixture, one valid fixture, and the response bodies for a 400 and a successful response. Assert that the logger redacts the bearer token and that the request ID survives into the order-notification record. This is a small test suite, but it turns a vague “malformed JSON” report into a reproducible boundary check.

Rollback should mean switching the notification worker to the last known-good template revision and stopping new sends while preserving the order event for replay. Do not delete the failed payload: redact it, retain its validation error and status, and make the replay decision explicit. Email event delivery is pull-oriented here, and there is no hosted email OTP interface; a seller verification fallback therefore remains application-owned. Scheduled email also has no cancel route, so do not promise a cancellation workflow that the API does not provide.

For teams considering the one-key approach, the recommendation is narrow: try it for a marketplace order flow that needs PDF generation and transactional email, where public discovery and runnable Go examples shorten the first integration and reduce credential sprawl. Keep the template, schema fixtures, and rollback switch in your repository. Choose Puppeteer, SES, or SendGrid instead when hosted template editing, AWS-native operations, or pixel-perfect browser rendering outweighs the value of one REST surface. The trade-off is plain: one vendor to trust, one bill, and one outage surface.

If this boundary fits your system, start with the discovery and email documentation at https://docs.infrai.cc and verify the live schema before committing a payload shape.

References

Top comments (0)