API Reference

Complete reference for the Postally REST API. All endpoints require authentication and return JSON responses.

Base URL

https://app.postally.io/api/v1

Authentication

All API requests require a valid API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Accounts

GET/accounts

Retrieve all connected social media accounts.

Response

{
  "accounts": [
    {
      "id": "acc_123456",
      "platform": "twitter",
      "username": "@yourhandle",
      "status": "connected",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}

POST/accounts

Connect a new social media account.

Request Body

{
  "platform": "twitter",
  "oauth_token": "your_oauth_token",
  "oauth_secret": "your_oauth_secret"
}

Posts

GET/posts

Retrieve all posts (scheduled and published).

Query Parameters

statusFilter by status: scheduled, published, failed

platformFilter by platform: twitter, instagram, etc.

POST/posts

Create and schedule a new post.

Request Body

{
  "content": "Your post content here",
  "platforms": ["twitter", "instagram"],
  "schedule_time": "2024-01-01T12:00:00Z",
  "media": ["image_url_1", "image_url_2"],
  "hashtags": ["#social", "#marketing"]
}

Analytics

GET/analytics

Get analytics data for your posts and accounts.

Query Parameters

date_fromStart date (ISO 8601)

date_toEnd date (ISO 8601)

AI Content Generation

POST/ai/generate

Generate AI-powered content for social media posts.

Request Body

{
  "prompt": "Create a post about sustainable fashion",
  "platform": "instagram",
  "tone": "professional",
  "include_hashtags": true,
  "max_length": 280
}

Rate Limits

API requests are limited to 1000 requests per hour per API key. Rate limit headers are included in all responses.