REST API for Email Marketing: Complete Developer Guide

Building email functionality into your app? DoPosta's REST API provides programmatic access to all features: send emails, manage lists, track analytics, configure servers—everything you can do in the dashboard, you can do via API.

This guide covers authentication, key endpoints, webhooks, rate limits, and best practices for integrating DoPosta's 47+ API endpoints.

API Overview

**Base URL**: https://api.doposta.com/v1

**Authentication**: JWT Bearer tokens

**Format**: JSON request/response

**Rate Limits**: Tiered by plan (500-10,000 requests/hour)

**Documentation**: Full Swagger/OpenAPI spec available

Authentication

Getting API Keys

Log into DoPosta dashboard. Navigate to **Settings > API Keys > Generate New Key**. Save your API key securely (shown only once). Use in Authorization header: `Authorization: Bearer YOUR_API_KEY`

Making Authenticated Requests

Example with curl: `curl -H "Authorization: Bearer YOUR_API_KEY" https://api.doposta.com/v1/campaigns`

Example with JavaScript: `fetch('https://api.doposta.com/v1/campaigns', { headers: { 'Authorization': 'Bearer ' + API_KEY }})`

Token Refresh

Access tokens expire after 24 hours. Refresh automatically using refresh token endpoint. DoPosta SDKs handle this automatically.

Core API Endpoints

Campaign Management

**POST /campaigns** - Create new campaign

**GET /campaigns** - List all campaigns

**GET /campaigns/:id** - Get campaign details

**PUT /campaigns/:id** - Update campaign

**DELETE /campaigns/:id** - Delete campaign

**POST /campaigns/:id/send** - Send campaign immediately

**POST /campaigns/:id/schedule** - Schedule for later

Example: Create Campaign

Send POST request to /campaigns with JSON body containing name, subject, from email, HTML content, plain text content, and recipient list ID.

Contact Management

**POST /contacts** - Add single contact

**POST /contacts/bulk** - Import multiple contacts

**GET /contacts** - List contacts with pagination

**GET /contacts/:id** - Get contact details

**PUT /contacts/:id** - Update contact

**DELETE /contacts/:id** - Remove contact

**POST /contacts/verify** - Verify email address

Example: Bulk Import Contacts

POST to /contacts/bulk with array of contact objects including email, name, custom fields, tags, and subscription status.

List Management

**POST /lists** - Create new list

**GET /lists** - Get all lists

**PUT /lists/:id** - Update list

**POST /lists/:id/contacts** - Add contacts to list

**DELETE /lists/:id/contacts/:contactId** - Remove from list

Email Sending

**POST /send** - Send single transactional email

**POST /send/bulk** - Send batch emails

**POST /send/template** - Send using template

Example: Send Transactional Email

POST to /send with recipient email, subject, HTML/text content, from details, and optional attachments.

Analytics & Reporting

**GET /analytics/campaigns/:id** - Campaign stats

**GET /analytics/overview** - Account-level metrics

**GET /analytics/engagement** - Engagement trends

**GET /tracking/opens** - Open tracking data

**GET /tracking/clicks** - Click tracking data

**GET /tracking/bounces** - Bounce reports

**GET /tracking/complaints** - Spam complaints

Server Management

**POST /servers/smtp** - Add SMTP server

**GET /servers** - List all servers

**PUT /servers/:id** - Update server config

**DELETE /servers/:id** - Remove server

**GET /servers/:id/status** - Check server health

**POST /servers/pmta/vmta** - Create PMTA VMTA

Suppression Management

**POST /suppressions** - Add to suppression list

**GET /suppressions** - List suppressed emails

**DELETE /suppressions/:email** - Remove from suppression

**POST /suppressions/bulk** - Bulk suppression import

Webhooks

Receive real-time notifications for email events.

Available Webhook Events

**email.sent** - Email successfully handed off to MTA

**email.delivered** - Confirmed delivery to recipient

**email.opened** - Recipient opened email

**email.clicked** - Recipient clicked link

**email.bounced** - Email bounced (hard or soft)

**email.complained** - Spam complaint received

**email.unsubscribed** - Recipient unsubscribed

**campaign.sent** - Campaign finished sending

**list.imported** - Contact import completed

Webhook Setup

Navigate to **Settings > Webhooks > Add Endpoint**. Enter your webhook URL, select events to receive, and configure secret for signature verification.

Webhook Payload

All webhooks POST JSON with event type, timestamp, data object, and HMAC signature for verification.

Example: email.opened Payload

JSON with event type opened, timestamp, email address, campaign ID, IP address, user agent, and location.

Signature Verification

Verify webhook authenticity using HMAC-SHA256 signature. Example in Node.js verifies using crypto library.

Rate Limiting

API rate limits by plan tier:

**Starter**: 500 requests/hour

**Professional**: 2,000 requests/hour

**Enterprise**: 10,000 requests/hour

Rate limit headers included in every response showing limit, remaining, and reset time.

Handling Rate Limits

Implement exponential backoff. Check X-RateLimit-Remaining header. Queue requests when approaching limit. Use bulk endpoints when possible (one request vs many).

Error Handling

HTTP Status Codes

**200 OK** - Successful request

**201 Created** - Resource created

**400 Bad Request** - Invalid parameters

**401 Unauthorized** - Invalid/missing API key

**403 Forbidden** - Insufficient permissions

**404 Not Found** - Resource doesn't exist

**429 Too Many Requests** - Rate limit exceeded

**500 Server Error** - DoPosta server issue

Error Response Format

All errors return JSON with error code, message, and optional details array.

Best Practices

Security

Never expose API keys in client-side code. Rotate keys quarterly. Use environment variables for key storage. Implement IP whitelisting when possible.

Performance

Use bulk endpoints for batch operations. Implement caching for frequently accessed data. Paginate large result sets. Compress requests/responses.

Reliability

Implement retry logic with exponential backoff. Handle webhook failures gracefully. Monitor API usage and errors. Set up timeout limits (30 seconds recommended).

SDK & Libraries

Official SDKs

**Node.js**: `npm install @doposta/node`

**Python**: `pip install doposta`

**PHP**: `composer require doposta/doposta-php`

**Ruby**: `gem install doposta`

SDK Example (Node.js)

Initialize client with API key, create campaign, send immediately with full configuration.

Common Integration Patterns

Pattern 1: User Signup Email

On user registration in your app: call /send API with welcome email template, track delivery via webhook, and update user record.

Pattern 2: Transactional Email

For order confirmations, password resets, etc.: use /send/template endpoint with dynamic data, set high priority flag, and receive delivery confirmation via webhook.

Pattern 3: Marketing Automation

Trigger-based campaigns: webhook from your app triggers campaign send, DoPosta handles delivery and tracking, and results sync back to your system.

API vs Dashboard: When to Use Each

**Use API for**: Integration with existing apps, automated workflows, custom functionality, high-volume operations.

**Use Dashboard for**: Campaign creation and design, analytics visualization, manual list management, system configuration.

Monitoring & Debugging

API Logs

View all API calls in **Settings > API Logs**. See request/response, status codes, and timestamps for debugging.

Testing Environment

DoPosta provides sandbox mode for testing without affecting production data or sending real emails.

Conclusion

DoPosta's REST API provides complete programmatic control over your email infrastructure. With 47+ endpoints, comprehensive webhooks, and official SDKs, integrate email into any application.

Ready to build with DoPosta's API? [Start your free trial](/register) and get API access instantly.