curl --request POST \
  --url https://api.tempmaillab.com/v1/emails \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '{}'

{
  "data": {
    "id": "<string>",
    "address": "jsmith@example.com",
    "local_part": "<string>",
    "domain": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "expires_at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "The request parameters are invalid.",
    "request_id": "req_a1b2c3d4e5f6g7h8",
    "details": [
      {
        "field": "cursor",
        "reason": "invalid"
      }
    ]
  }
}

{
  "error": {
    "code": "invalid_api_key",
    "message": "A valid API key is required.",
    "request_id": "req_a1b2c3d4e5f6g7h8"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "details": [
      {
        "reason": "<string>",
        "field": "<string>"
      }
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "details": [
      {
        "reason": "<string>",
        "field": "<string>"
      }
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "details": [
      {
        "reason": "<string>",
        "field": "<string>"
      }
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "details": [
      {
        "reason": "<string>",
        "field": "<string>"
      }
    ]
  }
}

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry after the indicated delay.",
    "request_id": "req_a1b2c3d4e5f6g7h8"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "details": [
      {
        "reason": "<string>",
        "field": "<string>"
      }
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "details": [
      {
        "reason": "<string>",
        "field": "<string>"
      }
    ]
  }
}

Create a temporary email

Atomically reserves a new address for 30 days. Omit local_part and domain to let the service select both, or provide either/both. The address starts receiving through the isolated API mail system immediately after the reservation becomes active; no website session, browser presence, or dashboard availability is required.

Idempotency keys are scoped to the authenticated account and operation. Replaying the same key and equivalent request returns the original resource and is not charged again. Reusing a key with a different request returns 409. An address is never reallocated after expiry.

POST

emails

curl --request POST \
  --url https://api.tempmaillab.com/v1/emails \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '{}'

{
  "data": {
    "id": "<string>",
    "address": "jsmith@example.com",
    "local_part": "<string>",
    "domain": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "expires_at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "The request parameters are invalid.",
    "request_id": "req_a1b2c3d4e5f6g7h8",
    "details": [
      {
        "field": "cursor",
        "reason": "invalid"
      }
    ]
  }
}

{
  "error": {
    "code": "invalid_api_key",
    "message": "A valid API key is required.",
    "request_id": "req_a1b2c3d4e5f6g7h8"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "details": [
      {
        "reason": "<string>",
        "field": "<string>"
      }
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "details": [
      {
        "reason": "<string>",
        "field": "<string>"
      }
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "details": [
      {
        "reason": "<string>",
        "field": "<string>"
      }
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "details": [
      {
        "reason": "<string>",
        "field": "<string>"
      }
    ]
  }
}

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry after the indicated delay.",
    "request_id": "req_a1b2c3d4e5f6g7h8"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "details": [
      {
        "reason": "<string>",
        "field": "<string>"
      }
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "details": [
      {
        "reason": "<string>",
        "field": "<string>"
      }
    ]
  }
}

Authorizations

Authorization

string

header

required

Send a live API key in the Authorization header. Keys in query strings are rejected. A staging key never authenticates against production.

Headers

Idempotency-Key

string

required

Unique caller-generated value for safely retrying this creation. It is scoped to the authenticated account and operation and must not contain a secret or API key.

Required string length: 16 - 255

Pattern: ^[\x21-\x7E]+$

Body

application/json

local_part

string

Optional lowercase custom name. The server normalizes and validates it, rejects reserved names, and never reallocates a previously issued name.

Required string length: 1 - 64

Pattern: ^[a-z0-9](?:[a-z0-9._-]{0,62}[a-z0-9])?$

domain

string<hostname>

Optional active domain returned by GET /v1/domains.

Maximum string length: 253

Response

The email was created, or the original successful creation was replayed.

data

object

required

Show child attributes

Last modified on August 8, 2026

⌘I