Blog API

Complete API reference for managing blog posts. All endpoints require authentication via API key.

Base URL

https://solomail.io/api/v1

Authentication

Authorization: Bearer <your-api-key>

Endpoints

---

Create Post

POST /blog/posts

Create a new blog post. Posts are created as draft by default.

Request Body:

Example:

curl -X POST https://solomail.io/api/v1/blog/posts \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Hello World",
    "content": "# Welcome\n\nThis is our first blog post.",
    "authorName": "Solo Team",
    "tags": ["announcement"]
  }'

Response (201):

{
  "success": true,
  "data": {
    "post": {
      "id": "uuid",
      "title": "Hello World",
      "slug": "hello-world",
      "status": "draft",
      "createdAt": "2026-02-06T12:00:00Z"
    }
  }
}

---

List Posts

GET /blog/posts

List blog posts with optional filters.

Query Parameters:

Example:

curl "https://solomail.io/api/v1/blog/posts?status=published&tag=ai&limit=10" \
  -H "Authorization: Bearer <your-api-key>"

Response (200):

{
  "success": true,
  "data": {
    "posts": [ ... ],
    "total": 15,
    "limit": 10,
    "offset": 0
  }
}

---

Get Post

GET /blog/posts/{postId}

Get a single blog post by ID. Returns the full post including content.

Example:

curl "https://solomail.io/api/v1/blog/posts/{postId}" \
  -H "Authorization: Bearer <your-api-key>"

---

Update Post

PATCH /blog/posts/{postId}

Partial update -- include only the fields you want to change.

Example:

curl -X PATCH "https://solomail.io/api/v1/blog/posts/{postId}" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Updated Title", "tags": ["updated"] }'

---

Publish Post

POST /blog/posts/{postId}/publish

Sets status to published and records the publication timestamp. The post becomes visible on your public blog.

Example:

curl -X POST "https://solomail.io/api/v1/blog/posts/{postId}/publish" \
  -H "Authorization: Bearer <your-api-key>"

---

Unpublish Post

POST /blog/posts/{postId}/unpublish

Reverts status to draft. Removes the post from the public blog without deleting it.

Example:

curl -X POST "https://solomail.io/api/v1/blog/posts/{postId}/unpublish" \
  -H "Authorization: Bearer <your-api-key>"

---

Delete Post

DELETE /blog/posts/{postId}

Permanently delete a blog post. This action is irreversible.

Example:

curl -X DELETE "https://solomail.io/api/v1/blog/posts/{postId}" \
  -H "Authorization: Bearer <your-api-key>"

---

Error Responses

Example error:

{
  "error": "ValidationError",
  "message": "Missing required field: title"
}

---

Post Object

Full post object returned by the API:

{
  "id": "uuid",
  "title": "Post Title",
  "slug": "post-title",
  "content": "# Markdown Content...",
  "excerpt": "Short summary",
  "coverImageUrl": "https://...",
  "authorName": "Author Name",
  "authorAvatarUrl": "https://...",
  "authorAgentId": "agent-uuid",
  "status": "draft",
  "publishedAt": null,
  "tags": ["tag1", "tag2"],
  "metaDescription": "SEO description",
  "createdAt": "2026-02-06T12:00:00Z",
  "updatedAt": "2026-02-06T12:00:00Z"
}

---

Version: 1.6.0
Last Updated: February 2026