Technical Documentation | OmyPost Email System API & Integration Guide

Introduction

OmyPost API is a RESTful API that allows you to programmatically manage email accounts, send and receive emails, and perform other related operations.

Base URL

https://api.omypost.com/v1

Content Type

All requests and responses use application/json as the content type.

Authentication

All API requests require authentication using an API key. You can generate and manage API keys in your dashboard.

Bearer Token Authentication

Authorization: Bearer YOUR_API_KEY

API Key Generation

Log in to the OmyPost dashboard
Navigate to "Settings > API Keys"
Click "Generate New Key"
Set a description and permissions for the key
Save the generated key (shown only once)

API Reference

Email Accounts

POST /emails

Create a new email account

Request Parameters

Parameter	Type	Description
prefixRequired	string	Email prefix
type	string	Email type (permanent/temporary)
expiry_date	string	Expiration date for temporary email (ISO 8601 format)

Example Request

                    curl -X POST https://api.omypost.com/v1/emails \
                    -H "Authorization: Bearer YOUR_API_KEY" \
                    -H "Content-Type: application/json" \
                    -d '{
                        "prefix": "test",
                        "type": "permanent"
                    }'
                

Example Response

                    {
                        "id": "em_123456789",
                        "email": "test@omypost.com",
                        "type": "permanent",
                        "created_at": "2025-03-15T10:30:00Z",
                        "status": "active"
                    }
                

GET /emails

Get a list of all email accounts

Query Parameters

Parameter	Type	Description
page	integer	Page number (default: 1)
limit	integer	Items per page (default: 20, max: 100)
type	string	Filter by type (permanent/temporary)

Webhooks

Receive real-time notifications for emails and events via Webhooks.

Configure Webhook

POST /webhooks

Create a new Webhook configuration

Request Parameters

Parameter	Type	Description
urlRequired	string	URL to receive notifications
events	array	List of events to receive notifications for
secret	string	Secret key for verifying Webhook requests

SDK

We provide SDKs for multiple programming languages to help you integrate OmyPost API quickly.

Official SDKs

Python SDK
Node.js SDK
Java SDK
PHP SDK

Installation Example (Python)

pip install omypost-python

Usage Example

                from omypost import OmyPost

                client = OmyPost('YOUR_API_KEY')

                # Create a new email account
                email = client.emails.create(
                    prefix='test',
                    type='permanent'
                )

                print(f"Created email: {email.address}")
            

Examples

Here are some code examples for common use cases.

Create Multiple Email Accounts

                import json
                import requests

                api_key = 'YOUR_API_KEY'
                base_url = 'https://api.omypost.com/v1'

                headers = {
                    'Authorization': f'Bearer {api_key}',
                    'Content-Type': 'application/json'
                }

                # Create multiple email accounts
                emails = [
                    {'prefix': 'test1', 'type': 'permanent'},
                    {'prefix': 'test2', 'type': 'temporary', 'expiry_date': '2025-12-31'}
                ]

                for email in emails:
                    response = requests.post(
                        f'{base_url}/emails',
                        headers=headers,
                        json=email
                    )
                    print(json.dumps(response.json(), indent=2))
            

Rate Limits

We enforce rate limits on API requests to ensure stability.

Rate Limit Rules

API Type	Time Window	Request Limit
Email Management	1 minute	60 requests
Email Sending	1 minute	120 requests
Other APIs	1 minute	180 requests

Error Handling

The API uses standard HTTP status codes to indicate the result of requests.

Common Error Codes

Status Code	Description	Solution
400	Invalid request parameters	Check request parameters for correctness
401	Unauthorized	Check API key for correctness
403	Insufficient permissions	Confirm API key has necessary permissions
429	Too many requests	Reduce request frequency or contact us to increase limits
500	Server error	Try again later or contact support team

Error Response Example

                {
                    "error": {
                        "code": "invalid_parameter",
                        "message": "Email prefix contains invalid characters",
                        "details": {
                            "field": "prefix",
                            "reason": "Only letters, numbers, and underscores are allowed"
                        }
                    }
                }
            