How to use Draftship with the OpenAI API

OpenAI's API is the most common LLM behind email-drafting code. The right pattern is Structured Outputs: define a JSON schema for your Draftship block format, pass it on every call, and the model returns conforming JSON. No parsing free-form text.

Why Structured Outputs matter

Free-form prompts produce drift. One run gives you "subject:" and another gives you a paragraph that buries the subject in the body. Structured Outputs (introduced in 2024) let you bind the model to a JSON schema. The output validates against the schema before returning to your code.

The schema for a Draftship-ready email

json
{
  "type": "object",
  "properties": {
    "subject": { "type": "string", "maxLength": 70 },
    "preheader": { "type": "string", "maxLength": 100 },
    "blocks": {
      "type": "array",
      "items": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "type": { "const": "heading" },
              "level": { "type": "integer", "minimum": 1, "maximum": 3 },
              "text": { "type": "string" }
            },
            "required": ["type", "level", "text"]
          },
          {
            "type": "object",
            "properties": {
              "type": { "const": "text" },
              "html": { "type": "string" }
            },
            "required": ["type", "html"]
          },
          {
            "type": "object",
            "properties": {
              "type": { "const": "button" },
              "label": { "type": "string", "maxLength": 30 },
              "href": { "type": "string", "format": "uri" }
            },
            "required": ["type", "label", "href"]
          }
        ]
      }
    }
  },
  "required": ["subject", "preheader", "blocks"]
}

This shape mirrors Draftship's internal block model. After parsing, each entry maps one-to-one onto a Draftship block.

API call with Structured Outputs

bash
curl -X POST https://api.openai.com/v1/chat/completions \
  -H 'Authorization: Bearer sk-...' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-4.1",
    "messages": [
      { "role": "system", "content": "You write marketing emails." },
      { "role": "user", "content": "Draft a launch email for..." }
    ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "draftship_email",
        "strict": true,
        "schema": { "...your schema..." }
      }
    }
  }'

With strict: true, the model is constrained to produce only valid JSON. Invalid generations are auto-retried client-side.

Prompt patterns that ship

The prompt body is more important than the model choice. Three patterns:

• Brand-anchored: include 2-3 real past emails as voice anchors. Cuts generic-marketing tone immediately.
• Constraint-heavy: "Subject under 50 chars, no emoji, no exclamation." More constraints = less drift.
• Negative examples: "Avoid these words: leverage, unlock, journey, synergy." Direct list of banned terms.

Image generation via DALL-E or GPT Image

OpenAI's image models can generate hero images for email. For Draftship's Image block, the workflow:

1. Prompt DALL-E or the image API for an asset at 1200x600 (2x retina-ready). 2. Save the URL or download to your CDN. 3. Paste the URL into Draftship's Image block.

Don't hotlink to OpenAI's URLs in production; they expire. Always download and host on your own CDN.

Test send checklist

• Validate JSON structure before mapping to Draftship blocks.
• Run the rendered email through the size checker.
• Send a test through your ESP.
• Verify all AI-generated links are real, not hallucinated.

When to use OpenAI vs Claude vs Gemini

All three produce passable email copy with the right prompts. Choose based on:

• Pricing tier you're already on
• Voice fit (test with the same prompt across all three)
• Tooling integration (Structured Outputs, tool use, file handling)

For a side-by-side, see Use Draftship with Claude and Use Draftship with Gemini.