{
  "openapi": "3.1.0",
  "info": {
    "title": "Lettermint Sending API",
    "version": "0.0.1",
    "description": "API for sending transactional emails. Authenticate using your Project API token via the `x-lettermint-token` header."
  },
  "servers": [
    {
      "url": "https://api.lettermint.co/v1"
    }
  ],
  "tags": [
    {
      "name": "Send"
    }
  ],
  "x-tagGroups": [
    {
      "name": "Sending",
      "tags": [
        "Send"
      ]
    }
  ],
  "security": [
    {
      "SendingApiToken": []
    }
  ],
  "paths": {
    "/send": {
      "post": {
        "operationId": "v1.sendMail",
        "summary": "Send an email",
        "tags": [
          "Send"
        ],
        "parameters": [
          {
            "name": "x-lettermint-token",
            "in": "header",
            "description": "Project API token for the project sending this email.",
            "schema": {
              "type": "string"
            },
            "example": "lm_..."
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "schema": {
              "type": "string"
            }
          }
        ],
        "x-code-samples": [
          {
            "lang": "shell",
            "label": "cURL",
            "source": "curl -X POST https://api.lettermint.co/v1/send \\\n  -H \"x-lettermint-token: $LETTERMINT_PROJECT_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"from\":\"John Doe <john@example.com>\",\"to\":[\"recipient@example.com\"],\"subject\":\"Hello\",\"text\":\"Sent with Lettermint.\"}'"
          },
          {
            "lang": "javascript",
            "label": "Node.js",
            "source": "const response = await fetch(\"https://api.lettermint.co/v1/send\", {\n  method: \"POST\",\n  headers: {\n    \"x-lettermint-token\": process.env.LETTERMINT_PROJECT_TOKEN,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    from: \"John Doe <john@example.com>\",\n    to: [\"recipient@example.com\"],\n    subject: \"Hello\",\n    text: \"Sent with Lettermint.\",\n  }),\n});"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SendMailRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message_id": {
                      "type": "string"
                    },
                    "status": {
                      "$ref": "#/components/schemas/MessageStatus"
                    }
                  },
                  "required": [
                    "message_id",
                    "status"
                  ]
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/ValidationException"
          }
        },
        "security": []
      }
    },
    "/send/batch": {
      "post": {
        "operationId": "v1.sendBatchMail",
        "description": "Send up to 500 emails in a single request. Each email in the batch supports the same parameters as the single send endpoint.",
        "summary": "Send multiple emails in a batch",
        "tags": [
          "Send"
        ],
        "parameters": [
          {
            "name": "x-lettermint-token",
            "in": "header",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SendBatchMailRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Array of message IDs and their status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "message_id": {
                        "type": "string"
                      },
                      "status": {
                        "$ref": "#/components/schemas/MessageStatus"
                      }
                    },
                    "required": [
                      "message_id",
                      "status"
                    ]
                  }
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/ValidationException"
          }
        },
        "security": []
      }
    },
    "/ping": {
      "get": {
        "operationId": "v1.ping",
        "description": "This endpoint can be used to check the API status and verify authentication.\nIt accepts both Team API tokens (via Bearer authentication) and Project API tokens (via X-Lettermint-Token header).",
        "summary": "Ping the API",
        "tags": [
          "Generic"
        ],
        "parameters": [
          {
            "name": "Authorization",
            "in": "header",
            "description": "Team API token using Bearer authentication. Format: `Bearer {team_token}`.",
            "schema": {
              "type": "string"
            },
            "example": "Bearer lm_team_..."
          },
          {
            "name": "X-Lettermint-Token",
            "in": "header",
            "description": "Project API token.",
            "schema": {
              "type": "string"
            },
            "example": "lm_..."
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "type": "integer",
                  "const": 200
                }
              }
            }
          }
        },
        "security": []
      }
    }
  },
  "components": {
    "securitySchemes": {
      "SendingApiToken": {
        "type": "apiKey",
        "in": "header",
        "name": "x-lettermint-token",
        "description": "Project API token for the project sending email. Create one in your project settings."
      }
    },
    "schemas": {
      "MessageStatus": {
        "type": "string",
        "enum": [
          "pending",
          "queued",
          "suppressed",
          "processed",
          "delivered",
          "opened",
          "clicked",
          "soft_bounced",
          "hard_bounced",
          "spam_complaint",
          "failed",
          "blocked",
          "policy_rejected",
          "unsubscribed"
        ],
        "title": "MessageStatus"
      },
      "SendMailRequest": {
        "type": "object",
        "properties": {
          "route": {
            "type": "string"
          },
          "from": {
            "type": "string"
          },
          "to": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "minItems": 1
          },
          "cc": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "bcc": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "reply_to": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "subject": {
            "type": "string",
            "maxLength": 998
          },
          "headers": {
            "type": "object",
            "description": "Custom headers to include in the email.",
            "examples": [
              {
                "X-Custom-Header": "custom-value",
                "X-Campaign-ID": "12345"
              }
            ],
            "additionalProperties": {
              "type": "string"
            }
          },
          "metadata": {
            "type": "object",
            "description": "Metadata to track with the email (not added as email headers).",
            "examples": [
              {
                "user_id": "123",
                "campaign_id": "welcome-2025"
              }
            ],
            "additionalProperties": {
              "type": "string"
            }
          },
          "tag": {
            "type": [
              "string",
              "null"
            ],
            "description": "Tag to categorize and filter emails (alphanumeric, underscores, hyphens, spaces allowed).",
            "examples": [
              "welcome-email"
            ]
          },
          "settings": {
            "type": [
              "object",
              "null"
            ],
            "description": "Per-email settings that override the selected route settings for this email only.",
            "examples": [
              {
                "track_opens": false,
                "track_clicks": true
              }
            ],
            "properties": {
              "track_opens": {
                "type": "boolean"
              },
              "track_clicks": {
                "type": "boolean"
              }
            }
          },
          "html": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 3
          },
          "text": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 3
          },
          "attachments": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "filename": {
                  "type": "string"
                },
                "content": {
                  "type": "string"
                },
                "content_type": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "The MIME type of the attachment. Supports parameters (e.g. `text/calendar; method=REQUEST`).\nIf omitted, detected automatically from content or filename.",
                  "example": "application/pdf",
                  "maxLength": 255
                },
                "content_id": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Content ID for inline attachments, referenced via `cid:` in HTML body.\nIf no `@` is present, `@lm` is appended automatically.",
                  "example": "logo-image",
                  "pattern": "^[a-zA-Z0-9._@-]+$",
                  "maxLength": 255
                }
              },
              "required": [
                "filename",
                "content"
              ]
            }
          }
        },
        "required": [
          "from",
          "to",
          "subject"
        ],
        "title": "SendMailRequest"
      },
      "SendBatchMailRequest": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "route": {
              "type": "string"
            },
            "from": {
              "type": "string"
            },
            "to": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "minItems": 1
            },
            "cc": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "bcc": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "reply_to": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "subject": {
              "type": "string",
              "maxLength": 998
            },
            "headers": {
              "type": "array",
              "description": "Custom headers to include in the email.",
              "examples": [
                {
                  "X-Custom-Header": "custom-value",
                  "X-Campaign-ID": "12345"
                }
              ],
              "items": {
                "type": "string"
              }
            },
            "metadata": {
              "type": "array",
              "description": "Metadata to track with the email (not added as email headers).",
              "examples": [
                {
                  "user_id": "123",
                  "campaign_id": "welcome-2025"
                }
              ],
              "items": {
                "type": "string"
              }
            },
            "tag": {
              "type": [
                "string",
                "null"
              ],
              "description": "Tag to categorize and filter emails (alphanumeric, underscores, hyphens, spaces allowed).",
              "examples": [
                "welcome-email"
              ]
            },
            "settings": {
              "type": [
                "object",
                "null"
              ],
              "description": "Per-email settings that override the selected route settings for this email only.",
              "examples": [
                {
                  "track_opens": false,
                  "track_clicks": true
                }
              ],
              "properties": {
                "track_opens": {
                  "type": "boolean"
                },
                "track_clicks": {
                  "type": "boolean"
                }
              }
            },
            "html": {
              "type": [
                "string",
                "null"
              ],
              "minLength": 3
            },
            "text": {
              "type": [
                "string",
                "null"
              ],
              "minLength": 3
            },
            "attachments": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "filename": {
                    "type": "string"
                  },
                  "content": {
                    "type": "string"
                  },
                  "content_type": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The MIME type of the attachment. Supports parameters (e.g. `text/calendar; method=REQUEST`).\nIf omitted, detected automatically from content or filename.",
                    "example": "application/pdf",
                    "maxLength": 255
                  },
                  "content_id": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Content ID for inline attachments, referenced via `cid:` in HTML body.\nIf no `@` is present, `@lm` is appended automatically.",
                    "example": "logo-image",
                    "pattern": "^[a-zA-Z0-9._@-]+$",
                    "maxLength": 255
                  }
                },
                "required": [
                  "filename",
                  "content"
                ]
              }
            }
          },
          "required": [
            "from",
            "to",
            "subject"
          ]
        },
        "minItems": 1,
        "title": "SendBatchMailRequest"
      }
    },
    "responses": {
      "ValidationException": {
        "description": "Validation error",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "message": {
                  "type": "string",
                  "description": "Errors overview."
                },
                "errors": {
                  "type": "object",
                  "description": "A detailed description of each field that failed validation.",
                  "additionalProperties": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              },
              "required": [
                "message",
                "errors"
              ]
            }
          }
        }
      }
    }
  }
}