API Reference

Drift REST API

Programmatically manage OOO sessions, emails, and playbooks.

Base URL

https://withdrift.io/api/v1

Requirement: API access is available on the Team Growth plan. Create API keys from Settings → Developer in your dashboard.

Authentication

All API requests require a valid API key passed in the Authorization header as a Bearer token.

curl https://withdrift.io/api/v1/ooo-sessions \
  -H "Authorization: Bearer drift_your_api_key_here"

API Key Scopes

When creating an API key, you select which scopes to grant. Each endpoint requires specific scopes:

Scope	Access
`read:ooo`	List and retrieve OOO sessions
`write:ooo`	Create, update, and delete OOO sessions
`read:emails`	List emails from OOO sessions
`read:playbook`	List and retrieve return playbooks

Rate Limits

API requests are limited to 100 requests per minute per API key. Rate limit status is returned in response headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests per minute
`X-RateLimit-Remaining`	Remaining requests in current window
`Retry-After`	Seconds to wait before retrying (only on 429)

Error Handling

Errors return a JSON body with an error object containing a message and code:

{
  "error": {
    "message": "OOO session not found",
    "code": "NOT_FOUND"
  }
}

Status Codes

Status	Code	Meaning
400	`VALIDATION_ERROR`	Invalid or missing request parameters
401	`UNAUTHORIZED`	Missing or invalid Authorization header
401	`INVALID_API_KEY`	API key is invalid or revoked
403	`INSUFFICIENT_SCOPE`	API key lacks required scopes
403	`FEATURE_NOT_AVAILABLE`	API access requires Team Growth plan
404	`NOT_FOUND`	Resource does not exist
409	`CONFLICT`	Overlapping OOO session
429	`RATE_LIMIT_EXCEEDED`	Too many requests
500	`INTERNAL_ERROR`	Unexpected server error

OOO Sessions

List OOO Sessions

GET

/api/v1/ooo-sessions

Retrieve a paginated list of your OOO sessions.

Query Parameters

Parameter	Type	Default	Description
`status`	string	—	Filter by status: `scheduled`, `active`, or `completed`
`limit`	integer	20	Results per page (max 100)
`offset`	integer	0	Number of results to skip

Response

{
  "data": [
    {
      "id": "sess_abc123",
      "start_date": "2026-03-20T00:00:00.000Z",
      "end_date": "2026-03-27T00:00:00.000Z",
      "return_date": "2026-03-28T00:00:00.000Z",
      "status": "scheduled",
      "stats": {
        "emails_received": 0,
        "emails_filtered": 0,
        "urgent_count": 0
      },
      "playbook_id": null,
      "created_at": "2026-03-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "has_more": false
  }
}

Get OOO Session

GET

/api/v1/ooo-sessions/:id

Retrieve a specific OOO session with playbook details.

Response

{
  "id": "sess_abc123",
  "start_date": "2026-03-20T00:00:00.000Z",
  "end_date": "2026-03-27T00:00:00.000Z",
  "return_date": "2026-03-28T00:00:00.000Z",
  "status": "completed",
  "auto_reply_message": "I'm currently out of office...",
  "stats": {
    "emails_received": 142,
    "emails_filtered": 98,
    "urgent_count": 3,
    "total_emails_synced": 142
  },
  "playbook": {
    "id": "pb_xyz789",
    "summary": "You received 142 emails...",
    "action_items": [...],
    "fyi_items": [...],
    "resolved_items": [...],
    "stats": {
      "total_emails": 142,
      "filtered_emails": 98,
      "time_saved_minutes": 240
    },
    "delivered_at": "2026-03-28T06:00:00.000Z",
    "viewed_at": "2026-03-28T08:15:00.000Z"
  },
  "created_at": "2026-03-15T10:30:00.000Z",
  "updated_at": "2026-03-27T23:59:00.000Z"
}

Create OOO Session

POST

/api/v1/ooo-sessions

Schedule a new OOO session.

Request Body

Field	Type	Required	Description
`start_date`	string (ISO 8601)	Yes	Start date of OOO period
`end_date`	string (ISO 8601)	Yes	End date of OOO period
`auto_reply_message`	string	No	Custom auto-reply message

Example

curl -X POST https://withdrift.io/api/v1/ooo-sessions \
  -H "Authorization: Bearer drift_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "start_date": "2026-03-20T00:00:00.000Z",
    "end_date": "2026-03-27T00:00:00.000Z",
    "auto_reply_message": "I am out of office until March 27."
  }'

Update OOO Session

PATCH

/api/v1/ooo-sessions/:id

Update a scheduled or active OOO session.

Request Body

Field	Type	Description
`start_date`	string (ISO 8601)	New start date
`end_date`	string (ISO 8601)	New end date
`auto_reply_message`	string	Updated auto-reply message
`status`	string	Set to `cancelled` to cancel a scheduled session

Note: Completed sessions cannot be modified. Only scheduled sessions can be cancelled via the status field.

Delete OOO Session

DELETE

/api/v1/ooo-sessions/:id

Delete a scheduled OOO session.

Only sessions with scheduled status can be deleted. Active sessions must be ended, not deleted.

curl -X DELETE https://withdrift.io/api/v1/ooo-sessions/sess_abc123 \
  -H "Authorization: Bearer drift_your_api_key_here"

Emails

List Emails

GET

/api/v1/emails

Retrieve emails captured during OOO sessions.

Query Parameters

Parameter	Type	Default	Description
`session_id`	string	—	Filter by OOO session
`category`	string	—	Filter: `urgent`, `action_required`, `fyi`, `newsletter`, `promotional`, `resolved`
`limit`	integer	50	Results per page (max 100)
`offset`	integer	0	Number of results to skip

Note: Email history is limited by your plan — 14 days (Personal), 30 days (Team Starter), or 90 days (Team Growth).

Response

{
  "data": [
    {
      "id": "em_abc123",
      "external_id": "18abc123def",
      "session_id": "sess_abc123",
      "thread_id": "thread_xyz",
      "subject": "Q1 Budget Review - Action Needed",
      "from_email": "manager@company.com",
      "from_name": "Jane Smith",
      "category": "action_required",
      "urgency_score": 8,
      "ai_summary": "Manager requesting budget approval by Friday.",
      "auto_replied": true,
      "received_at": "2026-03-22T14:30:00.000Z",
      "created_at": "2026-03-22T14:31:00.000Z"
    }
  ],
  "pagination": {
    "total": 142,
    "limit": 50,
    "offset": 0,
    "has_more": true
  }
}

Playbooks

List Playbooks

GET

/api/v1/playbooks

Retrieve your return playbooks.

Query Parameters

Parameter	Type	Default	Description
`session_id`	string	—	Filter by OOO session
`limit`	integer	20	Results per page (max 100)
`offset`	integer	0	Number of results to skip

Response

{
  "data": [
    {
      "id": "pb_xyz789",
      "ooo_session_id": "sess_abc123",
      "summary": "You received 142 emails during your week away...",
      "action_items": [...],
      "fyi_items": [...],
      "resolved_items": [...],
      "stats": {
        "total_emails": 142,
        "filtered_emails": 98,
        "time_saved_minutes": 240
      },
      "delivered_at": "2026-03-28T06:00:00.000Z",
      "viewed_at": "2026-03-28T08:15:00.000Z",
      "created_at": "2026-03-28T06:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "has_more": false
  }
}

Need help? Contact hello@withdrift.io