API Reference

The Pupam API allows you to integrate email management capabilities into your applications.

Authentication

All API requests require authentication using an API key.

Getting Your API Key

Log in to your Pupam account
Go to Settings → API Keys
Click Generate New Key
Copy your key and store it securely

Making Authenticated Requests

Include your API key in the request headers:

curl https://api.pupam.com/v1/emails \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Base URL

https://api.pupam.com/v1

Rate Limits

Plan	Requests per Hour
Free	1,000
Pro	10,000
Enterprise	100,000

Emails

List Emails

Retrieve a list of emails from your inbox.

Endpoint: GET /emails

Query Parameters:

Parameter	Type	Description	Default
`folder`	string	Filter by folder ID	all
`status`	string	`read`, `unread`, `starred`	all
`limit`	integer	Number of results (max 100)	25
`offset`	integer	Pagination offset	0
`sort`	string	`date`, `subject`, `from`	date
`order`	string	`asc`, `desc`	desc

Example Request:

curl https://api.pupam.com/v1/emails?limit=10&status=unread \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response:

{
  "data": [
    {
      "id": "email_abc123",
      "subject": "Welcome to Pupam",
      "from": {
        "email": "hello@pupam.com",
        "name": "Pupam Team"
      },
      "to": [
        {
          "email": "user@example.com",
          "name": "John Doe"
        }
      ],
      "date": "2025-10-24T10:30:00Z",
      "status": "unread",
      "folder": "inbox",
      "has_attachments": false,
      "snippet": "Thank you for signing up for Pupam..."
    }
  ],
  "meta": {
    "total": 150,
    "limit": 10,
    "offset": 0
  }
}

Get Email

Retrieve a specific email by ID.

Endpoint: GET /emails/:id

Example Request:

curl https://api.pupam.com/v1/emails/email_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response:

{
  "id": "email_abc123",
  "subject": "Welcome to Pupam",
  "from": {
    "email": "hello@pupam.com",
    "name": "Pupam Team"
  },
  "to": [
    {
      "email": "user@example.com",
      "name": "John Doe"
    }
  ],
  "cc": [],
  "bcc": [],
  "date": "2025-10-24T10:30:00Z",
  "status": "read",
  "folder": "inbox",
  "labels": ["welcome", "onboarding"],
  "has_attachments": false,
  "body": {
    "html": "<html>...</html>",
    "text": "Welcome to Pupam..."
  },
  "attachments": []
}

Send Email

Send a new email.

Endpoint: POST /emails

Request Body:

{
  "to": [
    {
      "email": "recipient@example.com",
      "name": "Jane Smith"
    }
  ],
  "subject": "Hello from Pupam API",
  "body": {
    "html": "<p>This is a test email</p>",
    "text": "This is a test email"
  },
  "cc": [],
  "bcc": [],
  "attachments": []
}

Example Request:

curl -X POST https://api.pupam.com/v1/emails \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": [{"email": "recipient@example.com"}],
    "subject": "Hello",
    "body": {"text": "Hello World"}
  }'

Example Response:

{
  "id": "email_xyz789",
  "status": "sent",
  "message": "Email sent successfully"
}

Update Email

Update email properties (mark as read, star, move folder, etc.).

Endpoint: PATCH /emails/:id

Request Body:

{
  "status": "read",
  "starred": true,
  "folder": "archive",
  "labels": ["important", "follow-up"]
}

Example Response:

{
  "id": "email_abc123",
  "status": "read",
  "starred": true,
  "folder": "archive",
  "labels": ["important", "follow-up"]
}

Delete Email

Move email to trash or permanently delete.

Endpoint: DELETE /emails/:id

Query Parameters:

Parameter	Type	Description	Default
`permanent`	boolean	Permanently delete (skip trash)	false

Example Request:

curl -X DELETE https://api.pupam.com/v1/emails/email_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response:

{
  "id": "email_abc123",
  "status": "deleted",
  "message": "Email moved to trash"
}

Folders

List Folders

Endpoint: GET /folders

Example Response:

{
  "data": [
    {
      "id": "folder_inbox",
      "name": "Inbox",
      "type": "system",
      "email_count": 150,
      "unread_count": 12
    },
    {
      "id": "folder_xyz123",
      "name": "Customers",
      "type": "custom",
      "email_count": 45,
      "unread_count": 3
    }
  ]
}

Create Folder

Endpoint: POST /folders

Request Body:

{
  "name": "VIP Customers",
  "parent_id": null,
  "color": "#FF5733"
}

Automation

List Workflows

Endpoint: GET /workflows

Example Response:

{
  "data": [
    {
      "id": "workflow_abc123",
      "name": "Auto-assign Support Emails",
      "enabled": true,
      "trigger": {
        "type": "email_received",
        "conditions": [
          {
            "field": "subject",
            "operator": "contains",
            "value": "support"
          }
        ]
      },
      "actions": [
        {
          "type": "assign",
          "params": {
            "team": "support",
            "method": "round_robin"
          }
        }
      ]
    }
  ]
}

Create Workflow

Endpoint: POST /workflows

Request Body:

{
  "name": "VIP Customer Alert",
  "enabled": true,
  "trigger": {
    "type": "email_received",
    "conditions": [
      {
        "field": "from",
        "operator": "in_list",
        "value": "vip_customers"
      }
    ]
  },
  "actions": [
    {
      "type": "notify",
      "params": {
        "channel": "slack",
        "message": "VIP customer email received"
      }
    },
    {
      "type": "set_priority",
      "params": {
        "priority": "high"
      }
    }
  ]
}

Analytics

Get Email Stats

Endpoint: GET /analytics/emails

Query Parameters:

Parameter	Type	Description
`period`	string	`day`, `week`, `month`, `year`
`start_date`	string	Start date (ISO 8601)
`end_date`	string	End date (ISO 8601)

Example Response:

{
  "period": "week",
  "total_emails": 450,
  "emails_sent": 120,
  "emails_received": 330,
  "average_response_time": "2h 15m",
  "by_day": [
    {
      "date": "2025-10-18",
      "received": 45,
      "sent": 18
    }
  ]
}

Webhooks

Subscribe to real-time events.

Available Events

email.received
email.sent
email.opened
email.clicked
email.replied

Create Webhook

Endpoint: POST /webhooks

Request Body:

{
  "url": "https://your-app.com/webhooks/pupam",
  "events": ["email.received", "email.sent"],
  "secret": "your_webhook_secret"
}

Webhook Payload

{
  "event": "email.received",
  "timestamp": "2025-10-24T10:30:00Z",
  "data": {
    "email_id": "email_abc123",
    "from": "sender@example.com",
    "subject": "New Email"
  }
}

Error Codes

Code	Description
200	Success
201	Created
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
429	Rate Limit Exceeded
500	Internal Server Error

Error Response Format:

{
  "error": {
    "code": "invalid_request",
    "message": "Missing required field: to",
    "details": {
      "field": "to",
      "reason": "required"
    }
  }
}

SDKs

Official SDKs available:

JavaScript/TypeScript: npm install @pupam/sdk
Python: pip install pupam
Ruby: gem install pupam
PHP: composer require pupam/sdk

JavaScript Example

import { Pupam } from '@pupam/sdk';

const client = new Pupam('YOUR_API_KEY');

// Send an email
await client.emails.send({
  to: [{ email: 'user@example.com' }],
  subject: 'Hello',
  body: { text: 'Hello World' }
});

// List emails
const emails = await client.emails.list({
  status: 'unread',
  limit: 10
});

Need help? Visit our support page or join our developer community.

API Reference

API Reference

Authentication

Getting Your API Key

Making Authenticated Requests

Base URL

Rate Limits

Emails

List Emails

Get Email

Send Email

Update Email

Delete Email

Folders

List Folders

Create Folder

Automation

List Workflows

Create Workflow

Analytics

Get Email Stats

Webhooks

Available Events

Create Webhook

Webhook Payload

Error Codes

SDKs

JavaScript Example

Was this helpful?

Need more help?

Related Documentation

Getting Started

API Reference