Dokkio API Documentation

Complete API reference for managing email addresses and accessing statistics. Build powerful email processing workflows with our RESTful API.

Get Your API Key Try API Playground

Quick Start

Authentication

All API requests require authentication using your organization's API key. Include it in the Authorization header as a Bearer token.

Authorization: Bearer YOUR_API_KEY

Base URL

All API endpoints are accessed via HTTPS at our base URL:

https://api.dokkio.io

Rate Limits

• 100 requests per minute for GET endpoints
• 50 requests per minute for POST/PUT/DELETE endpoints
• Rate limit headers included in responses

Response Format

All responses are in JSON format with consistent structure:

{ "success": true, "data": { ... }, "timestamp": "2024-01-20T14:30:00Z" }

API Endpoints

Endpoints

GET/api/v1/emails

List all email addresses for your organization

Parameters

Name	Type	Required	Description
active	boolean	Optional	Filter by active status (true/false)

Responses

200Successfully retrieved email addresses

{
  "success": true,
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "emailAddress": "orders@dokkio.app",
      "displayName": "Order Processing",
      "isActive": true,
      "extractionSchema": {
        "name": "Order Schema",
        "fields": [
          {
            "name": "order_id",
            "description": "The order identification number",
            "type": "string",
            "required": true
          }
        ]
      },
      "webhookUrl": "https://api.yourapp.com/webhooks/orders",
      "stats": {
        "emailsProcessed": 150,
        "webhooksDelivered": 148
      },
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-20T14:20:00Z"
    }
  ],
  "count": 1,
  "timestamp": "2024-01-20T14:30:00Z"
}

Code Examples

curl -X GET https://api.dokkio.io/api/v1/emails \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

const response = await fetch('https://api.dokkio.io/api/v1/emails', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
console.log(data);

import requests

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

response = requests.get(
    'https://api.dokkio.io/api/v1/emails',
    headers=headers
)

data = response.json()
print(data)

POST/api/v1/emails

Create a new email address for processing

Request Body

Email address configuration

{
  "emailAddress": "invoices@dokkio.app",
  "displayName": "Invoice Processing",
  "extractionSchema": {
    "name": "Invoice Schema",
    "description": "Extract invoice data from supplier emails",
    "fields": [
      {
        "name": "invoice_number",
        "description": "The invoice number",
        "type": "string",
        "required": true
      },
      {
        "name": "amount",
        "description": "Invoice total amount",
        "type": "number",
        "required": true
      },
      {
        "name": "due_date",
        "description": "Payment due date",
        "type": "date",
        "required": false
      }
    ]
  },
  "webhookUrl": "https://api.yourapp.com/webhooks/invoices"
}

Responses

201Email address created successfully

{
  "success": true,
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "emailAddress": "invoices@dokkio.app",
    "displayName": "Invoice Processing",
    "webhookSecret": "wh_secret_abc123..."
  },
  "message": "Email address created successfully"
}

409Email address already exists

Code Examples

curl -X POST https://api.dokkio.io/api/v1/emails \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "emailAddress": "invoices@dokkio.app",
    "displayName": "Invoice Processing",
    "extractionSchema": {
      "name": "Invoice Schema",
      "fields": [
        {
          "name": "invoice_number",
          "description": "The invoice number",
          "type": "string",
          "required": true
        }
      ]
    },
    "webhookUrl": "https://api.yourapp.com/webhooks/invoices"
  }'

const response = await fetch('https://api.dokkio.io/api/v1/emails', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    emailAddress: 'invoices@dokkio.app',
    displayName: 'Invoice Processing',
    extractionSchema: {
      name: 'Invoice Schema',
      fields: [
        {
          name: 'invoice_number',
          description: 'The invoice number',
          type: 'string',
          required: true
        }
      ]
    },
    webhookUrl: 'https://api.yourapp.com/webhooks/invoices'
  })
});

const data = await response.json();

GET/api/v1/emails/{id}

Get details of a specific email address

Parameters

Name	Type	Required	Description
id	string	Required	Email address ID

Responses

200Email address details retrieved successfully

404Email address not found

Code Examples

curl -X GET https://api.dokkio.io/api/v1/emails/507f1f77bcf86cd799439011 \
  -H "Authorization: Bearer YOUR_API_KEY"

PUT/api/v1/emails/{id}

Update an existing email address

Parameters

Name	Type	Required	Description
id	string	Required	Email address ID

Request Body

Fields to update

{
  "displayName": "Updated Display Name",
  "isActive": true,
  "extractionSchema": {
    "name": "Updated Schema",
    "fields": []
  }
}

Responses

200Email address updated successfully

Code Examples

curl -X PUT https://api.dokkio.io/api/v1/emails/507f1f77bcf86cd799439011 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"displayName": "Updated Name"}'

DELETE/api/v1/emails/{id}

Delete an email address (soft delete - sets isActive to false)

Parameters

Name	Type	Required	Description
id	string	Required	Email address ID

Responses

200Email address deleted successfully

Code Examples

curl -X DELETE https://api.dokkio.io/api/v1/emails/507f1f77bcf86cd799439011 \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/api/v1/emails/{id}/stats

Get processing statistics for a specific email address

Parameters

Name	Type	Required	Description
id	string	Required	Email address ID
days	integer	Optional	Number of days to include in statistics (default: 30)

Responses

200Statistics retrieved successfully

{
  "success": true,
  "data": {
    "totalEmailsProcessed": 150,
    "totalWebhooksDelivered": 148,
    "webhookSuccessRate": 98.67,
    "recentActivity": [
      {
        "date": "2024-01-20",
        "emailsProcessed": 12,
        "webhooksDelivered": 12,
        "averageProcessingTime": 1250
      }
    ]
  }
}

Code Examples

curl -X GET "https://api.dokkio.io/api/v1/emails/507f1f77bcf86cd799439011/stats?days=7" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/api/v1/stats

Get organization-wide statistics and analytics

Parameters

Name	Type	Required	Description
days	integer	Optional	Number of days to include in statistics (default: 30)

Responses

200Organization statistics retrieved successfully

{
  "success": true,
  "data": {
    "overview": {
      "totalEmailAddresses": 5,
      "activeEmailAddresses": 4,
      "totalEmailsProcessed": 1250,
      "totalWebhooksDelivered": 1235,
      "averageSuccessRate": 98.8
    },
    "usage": {
      "currentMonth": {
        "emailsProcessed": 450,
        "webhooksDelivered": 445,
        "uniqueEmailAddressesUsed": 3
      },
      "trend": {
        "emailsProcessedChange": 15.2,
        "webhooksDeliveredChange": 14.8
      }
    }
  }
}

Code Examples

curl -X GET https://api.dokkio.io/api/v1/stats \
  -H "Authorization: Bearer YOUR_API_KEY"

Webhook Payload

When emails are processed, extracted data is sent to your webhook URL with this payload structure:

{
  "email_id": "em_abc123def456",
  "email_address": "orders@dokkio.app",
  "timestamp": "2024-01-20T14:30:00Z",
  "email_data": {
    "to": "orders@dokkio.app",
    "from": "store@example.com",
    "subject": "Order Confirmation #12345",
    "extracted_data": {
      "order_id": "12345",
      "amount": 99.99,
      "customer_email": "customer@example.com",
      "items": ["Product A", "Product B"]
    }
  },
  "confidence": 0.95,
  "processing_time": 1250
}

Webhook Security

All webhook payloads are signed with HMAC-SHA256 using your webhook secret. Verify the signature using the X-Dokkio-Signature header.

// Node.js signature verification example
const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return signature === `sha256=${expectedSignature}`;
}

Error Codes

Client Errors (4xx)

400Bad Request - Invalid request format

401Unauthorized - Invalid API key

403Forbidden - Insufficient permissions

404Not Found - Resource does not exist

409Conflict - Resource already exists

429Too Many Requests - Rate limit exceeded

Server Errors (5xx)

500Internal Server Error

502Bad Gateway

503Service Unavailable

Error Response Format

{
  "success": false,
  "error": "Error message",
  "details": "Additional details",
  "timestamp": "2024-01-20T14:30:00Z"
}

SDKs and Libraries

JavaScript/TypeScript

Soon

Official Node.js SDK with full TypeScript support

npm install @dokkio/node

Coming Soon

Python

Soon

Python SDK for seamless integration

pip install dokkio

Coming Soon

PHP

Soon

Composer package for PHP applications

composer require dokkio/php

Coming Soon

Ready to Start Building?

Get your API key and start processing emails in minutes. Join thousands of developers building with Dokkio.

Get Your API Key Download OpenAPI Spec Contact Support