Testmail Inbox API
Retrieve test emails from programmable inboxes
OpenAPI Specification
openapi: 3.0.3
info:
title: Testmail GraphQL Inbox API
description: Full-featured GraphQL API for querying test emails from Testmail programmable inboxes. Supports advanced filtering, custom sorting, field selection, live queries, pagination, and spam reports. Authenticated via Bearer token in the Authorization header. The GraphQL endpoint accepts POST requests with a JSON body containing the query and optional variables.
version: 1.0.0
contact:
url: https://testmail.app/docs/
license:
name: Proprietary
url: https://testmail.app
servers:
- url: https://api.testmail.app/api
description: Testmail Production API
security:
- BearerAuth: []
tags:
- name: Inbox
description: Retrieve test emails from programmable inboxes
paths:
/json:
get:
operationId: getEmails
summary: Retrieve emails from a namespace inbox
description: Retrieves test emails from the specified namespace inbox. Supports filtering by tag, timestamp range, and pagination. Optionally waits for new emails with the livequery parameter. If livequery is active and no matching emails arrive within 60 seconds, the server returns HTTP 307 and the client must follow the redirect and resend the request.
tags:
- Inbox
parameters:
- name: apikey
in: query
required: true
description: API authentication key retrieved from the developer console.
schema:
type: string
- name: namespace
in: query
required: true
description: Target namespace identifier. Emails are routed to {namespace}.{tag}@inbox.testmail.app.
schema:
type: string
- name: tag
in: query
required: false
description: Filter by exact tag match.
schema:
type: string
- name: tag_prefix
in: query
required: false
description: Filter by tag prefix (wildcard prefix search).
schema:
type: string
- name: timestamp_from
in: query
required: false
description: Start time filter in milliseconds since Unix epoch.
schema:
type: integer
format: int64
- name: timestamp_to
in: query
required: false
description: End time filter in milliseconds since Unix epoch.
schema:
type: integer
format: int64
- name: limit
in: query
required: false
description: Maximum number of emails to return per request.
schema:
type: integer
default: 10
minimum: 1
maximum: 100
- name: offset
in: query
required: false
description: Number of emails to skip for pagination.
schema:
type: integer
default: 0
minimum: 0
maximum: 9899
- name: livequery
in: query
required: false
description: When true, the server waits for new matching emails before responding. Returns HTTP 307 after 60 seconds if no emails arrive; client must follow redirects.
schema:
type: boolean
default: false
- name: pretty
in: query
required: false
description: When true, prettifies (indents) the JSON response output.
schema:
type: boolean
default: false
- name: headers
in: query
required: false
description: When true, includes raw email headers in each email object.
schema:
type: boolean
default: false
- name: spam_report
in: query
required: false
description: When true, includes SpamAssassin spam analysis data (spam_score and spam_report) in each email object.
schema:
type: boolean
default: false
responses:
'200':
description: Successful response containing email list and pagination metadata.
content:
application/json:
schema:
$ref: '#/components/schemas/EmailListResponse'
examples:
success:
$ref: '#/components/examples/EmailListSuccess'
empty:
$ref: '#/components/examples/EmailListEmpty'
'307':
description: Temporary redirect issued by livequery when no matching emails arrive within 60 seconds. Client must follow the redirect and resend the request.
headers:
Location:
description: URL to resend the request to (same URL).
schema:
type: string
format: uri
'400':
description: Bad request — missing or invalid parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized — missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
EmailListResponse:
type: object
description: Response envelope for a list of emails.
required:
- result
- count
- limit
- offset
- emails
properties:
result:
type: string
enum:
- success
- fail
description: Indicates whether the API call succeeded.
example: success
message:
type: string
nullable: true
description: Human-readable message, populated on failure.
example: null
count:
type: integer
description: Total number of emails matching the query (before pagination).
example: 3
limit:
type: integer
description: Maximum emails returned per page as specified in the request.
example: 10
offset:
type: integer
description: Number of emails skipped as specified in the request.
example: 0
emails:
type: array
description: Array of email objects matching the query.
items:
$ref: '#/components/schemas/Email'
EmailHeader:
type: object
description: A single raw email header line.
properties:
line:
type: string
description: Full raw header line including name and value.
example: 'Content-Type: text/html; charset=utf-8'
key:
type: string
description: Header name/key in lowercase.
example: content-type
Email:
type: object
description: A single test email retrieved from a Testmail inbox.
properties:
from:
type: string
description: Sender email address.
example: sender@example.com
to:
type: string
description: Recipient email address in the testmail namespace.
example: mynamespace.mytag@inbox.testmail.app
subject:
type: string
description: Email subject line.
example: Welcome to Our Service
text:
type: string
description: Plain-text body of the email.
example: Please verify your account by clicking the link below.
html:
type: string
description: HTML body of the email.
example: <p>Please <a href="https://example.com/verify">verify</a> your account.</p>
tag:
type: string
description: Tag portion of the recipient address used to route the email.
example: mytag
timestamp:
type: integer
format: int64
description: Unix timestamp in milliseconds when the email was received.
example: 1686000000000
headers:
type: array
description: Raw email headers. Only present when headers=true is requested.
items:
$ref: '#/components/schemas/EmailHeader'
spam_score:
type: number
format: float
description: SpamAssassin spam score. Only present when spam_report=true. Scores above 5 are typically flagged as spam.
example: 1.2
spam_report:
type: string
description: Detailed SpamAssassin spam analysis report. Only present when spam_report=true.
example: 'SpamAssassin Score: 1.2
Tests: HTML_MESSAGE=0.001'
ErrorResponse:
type: object
description: Error response envelope.
required:
- result
properties:
result:
type: string
enum:
- fail
description: Always "fail" for error responses.
example: fail
message:
type: string
description: Human-readable error description.
example: 'Missing required parameter: namespace'
examples:
EmailListSuccess:
summary: Successful email retrieval
value:
result: success
message: null
count: 2
limit: 10
offset: 0
emails:
- from: sender@example.com
to: mynamespace.verify-user123@inbox.testmail.app
subject: Please verify your email address
text: Click here to verify your account.
html: <p>Click <a href="https://example.com/verify/abc123">here</a> to verify.</p>
tag: verify-user123
timestamp: 1686000000000
- from: no-reply@service.com
to: mynamespace.reset-user456@inbox.testmail.app
subject: Password reset request
text: Use this link to reset your password.
html: <p>Reset your <a href="https://example.com/reset/xyz789">password</a>.</p>
tag: reset-user456
timestamp: 1686001000000
EmailListEmpty:
summary: Empty inbox response
value:
result: success
message: null
count: 0
limit: 10
offset: 0
emails: []
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 'API key as Bearer token. Obtain from the Testmail developer console and pass as: Authorization: Bearer YOUR_API_KEY'