Inbox API

The Inbox API allows you to create, retrieve, and update inboxes for your organization. Each inbox can be optionally associated with a test.

POSThttps://api.octal.email/v1/inbox

Creates a new inbox

Parameters

prefixstring

Custom prefix for the inbox address. Can only contain letters, numbers, and hyphens. Cannot start or end with a hyphen. Must be 15 characters or less.

test_idstring

Test ID to associate with the inbox.

Responses

200Inbox created successfully


{
  "inbox": {
    "id": "cuid",
    "full_address": "custom.abc123.orgslug@emailoctal.com",
    "domain": "emailoctal.com",
    "test_id": "cuid",
    "emails": []
  }
}

400Invalid custom prefix or test ID

401API key required or invalid/expired API key

403Maximum inbox limit reached

500Internal server error

GEThttps://api.octal.email/v1/inbox/:address

Retrieves an inbox by address

Parameters

addressstring

required

Full inbox address.

Responses

200Inbox retrieved successfully


{
  "inbox": {
    "id": "cuid",
    "full_address": "custom.abc123.orgslug@emailoctal.com",
    "domain": "emailoctal.com",
    "test_id": "cuid",
    "emails": []
  }
}

400Missing or invalid address

401API key required or invalid/expired API key

404Inbox not found

500Internal server error

PATCHhttps://api.octal.email/v1/inbox/:address

Updates an inbox's test ID

Parameters

addressstring

required

Full inbox address.

test_idstring

required

New test ID to associate.

Responses

200Inbox updated successfully


{
  "inbox": {
    "id": "cuid",
    "full_address": "custom.abc123.orgslug@emailoctal.com",
    "domain": "emailoctal.com",
    "test_id": "cuid",
    "emails": []
  }
}

400Missing or invalid address, or invalid test ID

401API key required or invalid/expired API key

404Inbox not found

500Internal server error

Request Examples

const axios = require('axios');

const response = await axios({
  method: 'post',
  url: 'https://api.octal.email/v1/inbox',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY'
  },
  data: {
    prefix: 'custom',
    test_id: 'YOUR_TEST_ID'
  }
});

console.log(response.data);