DropMail.me API

https://dropmail.me/api/
Admin
DropMail.me is a GraphQL API for programmatically creating disposable email addresses and receiving...
Tokens:20,351
Snippets:140
Trust Score:8.9
Update:6 months ago
Show doc for...
Tokens:
Raw
### HTTP GET Request for Session

Source: https://dropmail.me/api

Example of initiating a session via a standard HTTP GET request.

```http
GET /api/graphql/?query=mutation+%7BintroduceSession+%7Bid%2C+expiresAt%2C+addresses+%7Baddress%7D%7D%7D HTTP/1.1
Host: dropmail.me
Accept: application/json
```

--------------------------------

### cURL Request for Session

Source: https://dropmail.me/api

Command line example to initiate a session.

```bash
curl https://dropmail.me/api/graphql/ -H 'Content-Type: application/json' \
 -d '{"query":"mutation {introduceSession {id, expiresAt, addresses {address}}}"}'
```

--------------------------------

### Install and Run dropmail-mcp CLI

Source: https://dropmail.me/api

Instructions for installing the dropmail-mcp package using pip or pipx and running it from the command line with an API token. Also mentions using 'uvx' for quick tests.

```bash
pip install dropmail-mcp   # or: pipx install dropmail-mcp
```

```bash
dropmail-mcp --token YOUR_TOKEN
```

```bash
uvx dropmail-mcp --token YOUR_TOKEN
```

--------------------------------

### MCP Example Usage

Source: https://dropmail.me/api

This example demonstrates a typical workflow using the MCP (Message Communication Protocol) for interacting with DropMail.me, suitable for AI assistants. It shows session creation, waiting for an email, and reading its content.

```text
❯ Sign me up for the free trial at example.com and give me the confirmation code 

● create_session  → tmpbox47@dropmail.me
● wait_for_email  → 📬 "Verify your email address" from promo@example.com arrived
● read_email      → Your code: **482-951**
```

--------------------------------

### Install DropMail MCP from Wheel

Source: https://dropmail.me/api

Install the DropMail MCP package from a specific wheel file URL.

```bash
pip install https://dropmail.me/static/dist/dropmail_mcp-latest.whl
```

--------------------------------

### List all sessions via HTTP GET

Source: https://dropmail.me/api

Perform a GET request to fetch session data.

```http
GET /api/graphql/?query=query+%7Bsessions+%7Bid%2C+expiresAt%2C+mails+%7BrawSize%2C+fromAddr%2C+toAddr%2C+downloadUrl%2C+text%2C+headerSubject%7D%7D%7D HTTP/1.1
Host: dropmail.me
Accept: application/json

```

--------------------------------

### List Domains NodeJS 'graphql-request' Example

Source: https://dropmail.me/api

A NodeJS example using the 'graphql-request' library to query the Dropmail.me API for a list of domains. Remember to replace the placeholder token with your actual API token.

```javascript
// See https://github.com/prisma-labs/graphql-request
import { request, gql } from 'graphql-request'

async function main() {
  const token = ''
  const endpoint = 'https://dropmail.me/api/graphql/' + token

  const query = gql`
    query {domains {id, name, introducedAt, expiresAt, availableVia}}
  `

  const data = await request(endpoint, query)
  console.log(JSON.stringify(data, undefined, 2))
}
main().catch((error) => console.error(error))
```

--------------------------------

### Query GraphQL API with cURL

Source: https://dropmail.me/api

Command line examples for interacting with the API.

```bash
curl https://dropmail.me/api/graphql/ -H 'Content-Type: application/json' \
 -d '{"query":"query mailWithHtml($sanitizerConfig: HtmlSanitizerConfig) { sessions { mails { fromAddr headerSubject text sanitizedHtml(sanitizerConfig: $sanitizerConfig) } } }","variables":{"sanitizerConfig":{"imgData":"keep","imgCid":"proxy","imgHttp":"keep"}}}'
```

```bash
$ curl --silent -H "Content-Type: application/x-www-form-urlencoded" https://dropmail.me/api/graphql/MY_TOKEN -d 'query=mutation {introduceSession {id, expiresAt, addresses{id, address}}}' | jq
{
  "data": {
    "introduceSession": {
      "id": "U2Vzc2lvbjqcMxamadJC_aLiPz_XL0lK",
      "expiresAt": "2021-02-18T01:40:02+00:00",
      "addresses": [
        {
          "id": "QWRkcmVzczqcMxamadJC_aLiPz_XL0lKOmRyb2ZAMTBtYWlsLm9yZw",
          "address": "example@10mail.org"
        }
      ]
    }
  }
}
```

--------------------------------

### Install DropMail MCP via PyPI

Source: https://dropmail.me/api

Install the DropMail MCP package using pip.

```bash
pip install dropmail-mcp
```

--------------------------------

### HTTP POST Request for Session

Source: https://dropmail.me/api

Example of initiating a session via a standard HTTP POST request.

```http
POST /api/graphql/ HTTP/1.1
Host: dropmail.me
Content-Type: application/json
Content-Length: 76
Accept: application/json

{"query":"mutation {introduceSession {id, expiresAt, addresses {address}}}"}
```

--------------------------------

### Session creation response example

Source: https://dropmail.me/api

The expected JSON response structure after executing the introduceSession mutation.

```json
{
  "data": {
    "introduceSession": {
      "id": "U2Vzc2lvbjqcMxamadJC_aLiPz_XL0lK",
      "expiresAt": "2021-02-18T04:20:00+00:00",
      "addresses": [
        {
          "address": "example@10mail.org"
        }
      ]
    }
  }
}
```

--------------------------------

### Handle successful email response

Source: https://dropmail.me/api

Example response containing a Mail object.

```json
{
  "data": {
    "session": {
      "mails": [
        {
          "toAddr": "example@10mail.org",
          "text": "Hello\r\n",
          "rawSize": 812,
          "headerSubject": "Hello",
          "fromAddr": "test@example.com",
          "downloadUrl": "https://dropmail.me/download/mail/gql:1:9c3316a6-69d2-42fd-a2e2-3f3fd72f494a/vb18co6tn6b4pv10hgr7lhaljcnrhvk5"
        }
      ]
    }
  }
}
```

--------------------------------

### Handle empty email response

Source: https://dropmail.me/api

Example response when no emails are present in the session.

```json
{
  "data": {
    "session": {
      "mails": []
    }
  }
}
```

--------------------------------

### List Domains HTTP GET Request

Source: https://dropmail.me/api

Example of how to make an HTTP GET request to the Dropmail.me API to list domains. Ensure the 'query' parameter is correctly URL-encoded.

```http
GET /api/graphql/?query=query+%7Bdomains+%7Bid%2C+name%2C+introducedAt%2C+expiresAt%2C+availableVia%7D%7D HTTP/1.1
Host: dropmail.me
Accept: application/json


```

--------------------------------

### Handle expired session error

Source: https://dropmail.me/api

Example response when the session has expired or is not found.

```json
{
  "data": {
    "session": null
  },
  "errors": [
    {
      "path": ["session"],
      "message": "session_not_found",
      "extensions": {
        "code": "SESSION_NOT_FOUND"
      }
    }
  ]
}
```

--------------------------------

### Query GraphQL API via HTTP

Source: https://dropmail.me/api

Examples of executing GraphQL queries using standard HTTP methods.

```HTTP
GET /api/graphql/?query=query+mailWithHtml%28%24sanitizerConfig%3A+HtmlSanitizerConfig%29+%7B+sessions+%7B+mails+%7B+fromAddr+headerSubject+text+sanitizedHtml%28sanitizerConfig%3A+%24sanitizerConfig%29+%7D+%7D+%7D&variables=%7B%22sanitizerConfig%22%3A%7B%22imgData%22%3A%22keep%22%2C%22imgCid%22%3A%22proxy%22%2C%22imgHttp%22%3A%22keep%22%7D%7D HTTP/1.1
Host: dropmail.me
Accept: application/json
```

```HTTP
POST /api/graphql/ HTTP/1.1
Host: dropmail.me
Content-Type: application/json
Content-Length: 258
Accept: application/json

{"query":"query mailWithHtml($sanitizerConfig: HtmlSanitizerConfig) { sessions { mails { fromAddr headerSubject text sanitizedHtml(sanitizerConfig: $sanitizerConfig) } } }","variables":{"sanitizerConfig":{"imgData":"keep","imgCid":"proxy","imgHttp":"keep"}}}
```

--------------------------------

### GraphQL Error Response Example

Source: https://dropmail.me/api

Illustrates a typical GraphQL error response, including the 'errors' array with 'message', 'path', and 'extensions.code'. Handle the 'errors' field before processing 'data'. Some errors like 'SESSION_NOT_FOUND' are permanent.

```json
{
  "data": {
    "session": {
      "id": "U2Vzc2lvbjphYmNkZWY=",
      "mails": null
    }
  },
  "errors": [{
    "message": "Request quota exceeded",
    "path": ["session", "mails"],
    "extensions": {
      "code": "RATE_LIMIT_EXCEEDED",
      "captcha": {…}
    }
  }]
}
```

--------------------------------

### List Domains GraphQL Query

Source: https://dropmail.me/api

A GraphQL query to retrieve a list of available domains, including their ID, name, introduction date, expiration date, and availability status. This query can be used with GET or POST requests.

```graphql
{
  "query": "query {domains {id, name, introducedAt, expiresAt, availableVia}}"
}
```

--------------------------------

### GET /api/graphql/ - List Domains

Source: https://dropmail.me/api

Retrieves a list of available email domains using a GraphQL query.

```APIDOC
## GET /api/graphql/

### Description
Retrieves a list of available email domains including their ID, name, introduction date, expiration date, and availability methods.

### Method
GET

### Endpoint
/api/graphql/?query=query {domains {id, name, introducedAt, expiresAt, availableVia}}

### Response
#### Success Response (200)
- **data** (object) - The requested domain information.
```

--------------------------------

### Add a Personal Domain

Source: https://dropmail.me/api

Use the `addDomain` mutation to register your personal domain with DropMail. This mutation validates your DNS setup and requires a password for future management. Ensure your domain's MX records are correctly configured before calling this mutation.

```graphql
mutation {
  addDomain(input: {name: "example.com",
                    adminPassword: "my-secret-password"}) {
    id,
    name,
    availableVia
  }
}
```

--------------------------------

### List Domains HTTP POST Request

Source: https://dropmail.me/api

Example of how to make an HTTP POST request to the Dropmail.me API to list domains. The GraphQL query is sent in the JSON request body.

```http
POST /api/graphql/ HTTP/1.1
Host: dropmail.me
Content-Type: application/json
Content-Length: 77
Accept: application/json

{"query":"query {domains {id, name, introducedAt, expiresAt, availableVia}}"}
```

--------------------------------

### Introduce Session

Source: https://dropmail.me/api

Creates a new session, optionally with an initial email address.

```APIDOC
## POST /graphql

### Description
Initializes a new session. You can specify a domain ID or request a permanent domain only.

### Method
POST

### Endpoint
/graphql

### Request Body
- **withAddress** (boolean) - Required - Whether to create an address immediately.
- **domainId** (string) - Optional - The ID of the domain to use.
- **permanentDomainOnly** (boolean) - Optional - If true, only returns permanent domains.

### Request Example
mutation {
    introduceSession(input: {withAddress: true, domainId: "RG9tYWluOjE="}) {
        id,
        addresses {
          address
        }
    }
}
```

--------------------------------

### List all sessions with Python

Source: https://dropmail.me/api

Use the gql library to fetch session data.

```python
# See https://gql.readthedocs.io/en/latest/index.html
from gql import Client, gql
from gql.transport.aiohttp import AIOHTTPTransport

token = ""
transport = AIOHTTPTransport(url="https://dropmail.me/api/graphql/" + token)
client = Client(transport=transport, fetch_schema_from_transport=True)
query = gql("query {sessions {id, expiresAt, mails {rawSize, fromAddr, toAddr, downloadUrl, text, headerSubject}}}")
result = client.execute(query)
print(result)
```

--------------------------------

### Introduce Session with Python gql

Source: https://dropmail.me/api

Uses the AIOHTTP transport to perform the session mutation.

```python
# See https://gql.readthedocs.io/en/latest/index.html
from gql import Client, gql
from gql.transport.aiohttp import AIOHTTPTransport

token = ""
transport = AIOHTTPTransport(url="https://dropmail.me/api/graphql/" + token)
client = Client(transport=transport, fetch_schema_from_transport=True)
query = gql("mutation {introduceSession {id, expiresAt, addresses {address}}}")
result = client.execute(query)
print(result)
```

--------------------------------

### Configure GitHub Copilot CLI MCP

Source: https://dropmail.me/api

Set up the DropMail server configuration for the GitHub Copilot CLI.

```json
{
  "mcpServers": {
    "dropmail": {
      "command": "dropmail-mcp",
      "env": {
        "DROPMAIL_TOKEN": "${DROPMAIL_TOKEN}"
      }
    }
  }
}
```

--------------------------------

### List all sessions with Python over WebSocket

Source: https://dropmail.me/api

Use the gql library with WebSocket transport.

```python
# See https://gql.readthedocs.io/en/latest/transports/websockets.html
from gql import Client, gql
from gql.transport.websockets import WebsocketsTransport

token = ""
transport = WebsocketsTransport(url="wss://dropmail.me/api/graphql/" + token + "/websocket")
client = Client(transport=transport, fetch_schema_from_transport=True)
query = gql("query {sessions {id, expiresAt, mails {rawSize, fromAddr, toAddr, downloadUrl, text, headerSubject}}}")
result = client.execute(query)
print(result)
```

--------------------------------

### Get Domains API

Source: https://dropmail.me/api

Retrieves a list of available domains that can be used for email addresses.

```APIDOC
## GET /api/graphql/

### Description
Retrieves a list of available domains.

### Method
GET

### Endpoint
/api/graphql/

### Query Parameters
- **query** (string) - Required - The GraphQL query to fetch domains.

### Request Example
```
GET /api/graphql/?query=query+%7Bdomains+%7Bid%2C+name%2C+introducedAt%2C+expiresAt%2C+availableVia%7D%7D HTTP/1.1
Host: dropmail.me
Accept: application/json
```

### Response
#### Success Response (200)
- **data.domains** (array) - A list of available domains.
  - **id** (string) - The ID of the domain.
  - **name** (string) - The name of the domain.
  - **introducedAt** (string) - The introduction date of the domain.
  - **expiresAt** (string) - The expiration date of the domain.
  - **availableVia** (array) - A list of methods through which the domain is available.

#### Response Example
```json
{
  "data": {
    "domains": [
      {
        "id": "domain_id_1",
        "name": "example.com",
        "introducedAt": "2023-01-01T00:00:00Z",
        "expiresAt": "2024-12-31T23:59:59Z",
        "availableVia": ["http", "smtp"]
      }
    ]
  }
}
```
```

--------------------------------

### List all sessions with NodeJS

Source: https://dropmail.me/api

Use the graphql-request library to fetch session data.

```javascript
// See https://github.com/prisma-labs/graphql-request
import { request, gql } from 'graphql-request'

async function main() {
  const token = ''
  const endpoint = 'https://dropmail.me/api/graphql/' + token

  const query = gql`
    query {sessions {id, expiresAt, mails {rawSize, fromAddr, toAddr, downloadUrl, text, headerSubject}}}
  `

  const data = await request(endpoint, query)
  console.log(JSON.stringify(data, undefined, 2))
}
main().catch((error) => console.error(error))
```

--------------------------------

### Introduce Session with NodeJS graphql-request

Source: https://dropmail.me/api

Uses the graphql-request library to perform the session mutation.

```javascript
// See https://github.com/prisma-labs/graphql-request
import { request, gql } from 'graphql-request'

async function main() {
  const token = ''
  const endpoint = 'https://dropmail.me/api/graphql/' + token

  const query = gql`
    mutation {introduceSession {id, expiresAt, addresses {address}}}
  `

  const data = await request(endpoint, query)
  console.log(JSON.stringify(data, undefined, 2))
}
main().catch((error) => console.error(error))
```

--------------------------------

### GraphQL API Endpoint

Source: https://dropmail.me/api

The primary endpoint for interacting with the DropMail.me GraphQL API. Supports both GET and POST methods.

```APIDOC
## POST /api/graphql/${AUTH_TOKEN}

### Description
This endpoint allows you to send GraphQL queries and mutations to the DropMail.me service. It supports both GET and POST requests. For GET requests, parameters are appended as a query string. For POST requests, the body can be JSON or form-urlencoded.

### Method
POST, GET

### Endpoint
`https://dropmail.me/api/graphql/${AUTH_TOKEN}`

### Parameters
#### Query Parameters (for GET requests)
- **query** (string) - Required - The GraphQL query string.
- **variables** (object) - Optional - A JSON object containing variables for the query.
- **operationName** (string) - Optional - The name of the operation to execute.
- **extensions** (object) - Optional - GraphQL extensions.

#### Request Body (for POST requests)
- **query** (string) - Required - The GraphQL query string.
- **variables** (object) - Optional - A JSON object containing variables for the query.
- **operationName** (string) - Optional - The name of the operation to execute.
- **extensions** (object) - Optional - GraphQL extensions.

### Request Example (POST JSON)
```json
{
  "query": "mutation CreateSession($email: String) { createSession(email: $email) { id, email, expires } }",
  "variables": {
    "email": "test@dropmail.me"
  }
}
```

### Response
#### Success Response (200)
- **data** (object) - The result of the GraphQL query.
- **errors** (array) - An array of errors, if any occurred.

#### Response Example (JSON)
```json
{
  "data": {
    "createSession": {
      "id": "session_id_123",
      "email": "test@dropmail.me",
      "expires": "2023-10-27T10:00:00Z"
    }
  }
}
```

#### Response Example (multipart/mixed for subscriptions)
(Details omitted, refer to full specification for multipart/mixed format)
```

--------------------------------

### Introduce Session with Python gql over WebSocket

Source: https://dropmail.me/api

Uses the Websockets transport to perform the session mutation.

```python
# See https://gql.readthedocs.io/en/latest/transports/websockets.html
from gql import Client, gql
from gql.transport.websockets import WebsocketsTransport

token = ""
transport = WebsocketsTransport(url="wss://dropmail.me/api/graphql/" + token + "/websocket")
client = Client(transport=transport, fetch_schema_from_transport=True)
query = gql("mutation {introduceSession {id, expiresAt, addresses {address}}}")
result = client.execute(query)
print(result)
```

--------------------------------

### Pagination and Connections

Source: https://dropmail.me/api/schema.graphql

Information on how to paginate through email lists.

```APIDOC
## Pagination and Connections

### Description
These types are used for flexible pagination of email lists, following Relay specifications.

### Types
- **PageInfo**:
  - **hasNextPage** (Boolean!) - Indicates if there are more pages after the current one.
  - **hasPreviousPage** (Boolean!) - Indicates if there are more pages before the current one.
  - **startCursor** (String) - Cursor for fetching the previous page.
  - **endCursor** (String) - Cursor for fetching the next page.

- **SessionMailsConnection**:
  - **edges** ([SessionMailEdge]) - A list of edges, where each edge contains a mail node and its cursor.
  - **pageInfo** (PageInfo!) - Pagination information for the connection.
  - **totalCount** (Int!) - The total number of mails in the session.

- **SessionMailEdge**:
  - **node** (Mail!) - The actual mail object.
  - **cursor** (String!) - The cursor for this mail, used for pagination.
```

--------------------------------

### Configure Claude Desktop MCP

Source: https://dropmail.me/api

Add the DropMail server configuration to the Claude Desktop configuration file.

```json
{
  "mcpServers": {
    "dropmail": {
      "command": "dropmail-mcp",
      "env": {
        "DROPMAIL_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}
```

--------------------------------

### Create Session with Specific Domain

Source: https://dropmail.me/api

Create a new session with an initial address on a specific domain using its ID. The session will be assigned a unique login/username.

```graphql
mutation {
    introduceSession(input: {withAddress: true,
                             domainId: "RG9tYWluOjE="}) {
        id,
        addresses {
          address
        }
    }
}
    

```

--------------------------------

### Create a Session with a random Address

Source: https://dropmail.me/api

Use the introduceSession mutation to initialize a new session and generate a random email address.

```graphql
mutation {
    introduceSession {
        id,
        expiresAt,
        addresses {
          address
        }
    }
}
```

--------------------------------

### Create Session with Permanent Domain

Source: https://dropmail.me/api

Create a new session with an address on a permanent domain, ensuring it does not expire. This is useful for long-lived email addresses.

```graphql
mutation {
    introduceSession(input: {withAddress: true,
                             permanentDomainOnly: true}) {
        id,
        addresses {
          address,
          domain { name, expiresAt }
        }
    }
}
    

```

--------------------------------

### Introduce Session API

Source: https://dropmail.me/api

This endpoint introduces a new session, returning a new email address that can be used to send and receive emails.

```APIDOC
## POST /api/graphql/

### Description
Introduces a new session to generate a new email address.

### Method
POST

### Endpoint
/api/graphql/

### Request Body
- **query** (string) - Required - The GraphQL mutation to introduce a session.

### Request Example
```json
{
  "query": "mutation {introduceSession {id, expiresAt, addresses {address}}}"
}
```

### Response
#### Success Response (200)
- **data.introduceSession.id** (string) - The ID of the newly created session.
- **data.introduceSession.expiresAt** (string) - The expiration time of the session.
- **data.introduceSession.addresses** (array) - A list of email addresses associated with the session.
  - **address** (string) - The email address.

#### Response Example
```json
{
  "data": {
    "introduceSession": {
      "id": "some_session_id",
      "expiresAt": "2023-10-27T10:00:00Z",
      "addresses": [
        {
          "address": "random_email@example.com"
        }
      ]
    }
  }
}
```
```

--------------------------------

### Introduce Address

Source: https://dropmail.me/api

Adds a new email address to an existing session.

```APIDOC
## POST /graphql

### Description
Adds an additional email address to an existing session using the session ID.

### Method
POST

### Endpoint
/graphql

### Request Body
- **sessionId** (string) - Required - The ID of the session.
- **domainId** (string) - Optional - The ID of the domain to use.
- **permanentDomainOnly** (boolean) - Optional - If true, only returns permanent domains.

### Request Example
mutation {
    introduceAddress(input: {sessionId: "U2Vzc2lvbjqcMxamadJC_aLiPz_XL0lK"}) {
        address,
        restoreKey
    }
}
```

--------------------------------

### List all sessions via HTTP POST

Source: https://dropmail.me/api

Perform a POST request to fetch session data.

```http
POST /api/graphql/ HTTP/1.1
Host: dropmail.me
Content-Type: application/json
Content-Length: 113
Accept: application/json

{"query":"query {sessions {id, expiresAt, mails {rawSize, fromAddr, toAddr, downloadUrl, text, headerSubject}}}"}
```

--------------------------------

### Create Empty Session

Source: https://dropmail.me/api

Initiate a new session without any initial addresses. Addresses can be added later.

```graphql
mutation {
    introduceSession(input: {withAddress: false}) {
        id
    }
}


```

--------------------------------

### MCP Server Package

Source: https://dropmail.me/api

Information about the MCP server package for integrating DropMail with AI assistants.

```APIDOC
## MCP Server Package

### Description
The MCP server package allows direct integration of DropMail.me functionality with AI assistants and other tools, eliminating the need for direct GraphQL interaction.

### Usage
Available on PyPI. Provides tools to interact with DropMail without GraphQL knowledge.

### Example Workflow
```
❯ Sign me up for the free trial at example.com and give me the confirmation code 

● create_session  → tmpbox47@dropmail.me
● wait_for_email  → 📬 "Verify your email address" from promo@example.com arrived
● read_email      → Your code: **482-951**
```
```

--------------------------------

### POST /api/graphql/{token}

Source: https://dropmail.me/api

Performs a mutation to introduce a new temporary email session, returning session details and assigned email addresses.

```APIDOC
## POST /api/graphql/{token}

### Description
Creates a new temporary email session.

### Method
POST

### Endpoint
/api/graphql/{token}

### Parameters
#### Path Parameters
- **token** (string) - Required - The session token.

### Request Body
- **query** (string) - Required - The GraphQL mutation string: mutation {introduceSession {id, expiresAt, addresses{id, address}}}

### Response
#### Success Response (200)
- **data** (object) - Contains the session ID, expiration time, and list of addresses.

### Response Example
{
  "data": {
    "introduceSession": {
      "id": "U2Vzc2lvbjqcMxamadJC_aLiPz_XL0lK",
      "expiresAt": "2021-02-18T01:40:02+00:00",
      "addresses": [
        {
          "id": "QWRkcmVzczqcMxamadJC_aLiPz_XL0lKOmRyb2ZAMTBtYWlsLm9yZw",
          "address": "example@10mail.org"
        }
      ]
    }
  }
}
```

--------------------------------

### Query Domains with Python gql

Source: https://dropmail.me/api

Fetches domain information using the AIOHTTP transport.

```python
# See https://gql.readthedocs.io/en/latest/index.html
from gql import Client, gql
from gql.transport.aiohttp import AIOHTTPTransport

token = ""
transport = AIOHTTPTransport(url="https://dropmail.me/api/graphql/" + token)
client = Client(transport=transport, fetch_schema_from_transport=True)
query = gql("query {domains {id, name, introducedAt, expiresAt, availableVia}}")
result = client.execute(query)
print(result)
```

--------------------------------

### Fetch Compact Email Details via GraphQL API

Source: https://dropmail.me/api

A more concise GraphQL query to fetch essential details of received emails, such as raw size, sender, recipient, and download URL. Useful when full details are not needed.

```bash
$ curl --silent https://dropmail.me/api/graphql/MY_TOKEN -d 'query=query ($id: ID!) {session(id:$id) {mails{rawSize, fromAddr, toAddr, downloadUrl, text, headerSubject}} }&variables={"id": "U2Vzc2lvbjqcMxamadJC_aLiPz_XL0lK"}' | jq
```

```json
{
  "data": {
    "session": {
      "mails": [
        {
          "toAddr": "example@10mail.org",
          "text": "Hello\r\n",
          "rawSize": 812,
          "headerSubject": "Hello",
          "fromAddr": "test@example.com",
          "downloadUrl": "https://dropmail.me/download/mail/gql:1:9c3316a6-69d2-42fd-a2e2-3f3fd72f494a/vb18co6tn6b4pv10hgr7lhaljcnrhvk5"
        }
      ]
    }
  }
}
```

--------------------------------

### Fetch All Email Details via GraphQL API

Source: https://dropmail.me/api

Use this query to fetch all available details for received emails, including raw content and headers. Requires a valid API token and session ID.

```bash
$ curl --silent https://dropmail.me/api/graphql/MY_TOKEN -d 'query=query ($id: ID!) {session(id:$id) {id, expiresAt, mails{id, rawSize, raw, fromAddr, toAddr, receivedAt, downloadUrl, toAddrOrig, decodeStatus, text, headerFrom, headerSubject, html}, addresses{id, address, restoreKey} }}&variables={"id": "U2Vzc2lvbjqcMxamadJC_aLiPz_XL0lK"}' | jq
```

```json
{
  "data": {
    "session": {
      "mails": [
        {
          "toAddrOrig": "example@10mail.org",
          "toAddr": "example@10mail.org",
          "text": "Hello\r\n",
          "receivedAt": "2021-02-18T01:30:17+00:00",
          "rawSize": 812,
          "raw": "MIME-Version: 1.0\r\nMessage-ID: <test@mail.example.com>\r\nSubject: Hello\r\nFrom: Hello <test@example.com>\r\nTo: aonfmqcpw@example.com\r\nContent-Type: text/plain; charset=US-ASCII\r\n\r\nHello\r\n",
          "id": "TWFpbDqcMxamadJC/aLiPz/XL0lKOnZiMThjbzZ0bjZiNHB2MTBoZ3I3bGhhbGpjbnJodms1",
          "html": null,
          "headerSubject": "Hello",
          "headerFrom": "Hello <test@example.com>",
          "fromAddr": "test@example.com",
          "downloadUrl": "https://dropmail.me/download/mail/gql:1:9c3316a6-69d2-42fd-a2e2-3f3fd72f494a/vb18co6tn6b4pv10hgr7lhaljcnrhvk5",
          "decodeStatus": "OK"
        }
      ],
      "id": "U2Vzc2lvbjqcMxamadJC_aLiPz_XL0lK",
      "expiresAt": "2021-02-18T01:41:50+00:00",
      "addresses": [
        {
          "restoreKey": "0c88ea831f8f71bf3885f2b5bddd6c371",
          "id": "QWRkcmVzczqcMxamadJC_aLiPz_XL0lKOmRyb2ZAMTBtYWlsLm9yZw",
          "address": "example@10mail.org"
        }
      ]
    }
  }
}
```

--------------------------------

### Query Domains with Python gql over WebSocket

Source: https://dropmail.me/api

Fetches domain information using the Websockets transport.

```python
# See https://gql.readthedocs.io/en/latest/transports/websockets.html
from gql import Client, gql
from gql.transport.websockets import WebsocketsTransport

token = ""
transport = WebsocketsTransport(url="wss://dropmail.me/api/graphql/" + token + "/websocket")
client = Client(transport=transport, fetch_schema_from_transport=True)
query = gql("query {domains {id, name, introducedAt, expiresAt, availableVia}}")
result = client.execute(query)
print(result)
```

--------------------------------

### Introduce Session Mutation

Source: https://dropmail.me/api

GraphQL mutation query to create a new session.

```json
{
  "query": "mutation {introduceSession {id, expiresAt, addresses {address}}}"
}
```

--------------------------------

### Query GraphQL API with Python

Source: https://dropmail.me/api

Implementation using the gql library with different transport protocols.

```python
# See https://gql.readthedocs.io/en/latest/index.html
from gql import Client, gql
from gql.transport.aiohttp import AIOHTTPTransport

token = ""
transport = AIOHTTPTransport(url="https://dropmail.me/api/graphql/" + token)
client = Client(transport=transport, fetch_schema_from_transport=True)
query = gql("query mailWithHtml($sanitizerConfig: HtmlSanitizerConfig) { sessions { mails { fromAddr headerSubject text sanitizedHtml(sanitizerConfig: $sanitizerConfig) } } }",
            variable_values={"sanitizerConfig":{"imgData":"keep","imgCid":"proxy","imgHttp":"keep"}})
result = client.execute(query)
print(result)
```

```python
# See https://gql.readthedocs.io/en/latest/transports/websockets.html
from gql import Client, gql
from gql.transport.websockets import WebsocketsTransport

token = ""
transport = WebsocketsTransport(url="wss://dropmail.me/api/graphql/" + token + "/websocket")
client = Client(transport=transport, fetch_schema_from_transport=True)
query = gql("query mailWithHtml($sanitizerConfig: HtmlSanitizerConfig) { sessions { mails { fromAddr headerSubject text sanitizedHtml(sanitizerConfig: $sanitizerConfig) } } }",
            variable_values={"sanitizerConfig":{"imgData":"keep","imgCid":"proxy","imgHttp":"keep"}})
result = client.execute(query)
print(result)
```

--------------------------------

### List all sessions via cURL

Source: https://dropmail.me/api

Execute a GraphQL query using cURL.

```bash
curl https://dropmail.me/api/graphql/ -H 'Content-Type: application/json' \
 -d '{"query":"query {sessions {id, expiresAt, mails {rawSize, fromAddr, toAddr, downloadUrl, text, headerSubject}}}"}'
```

--------------------------------

### mutation addDomain

Source: https://dropmail.me/api

Registers a new personal domain with DropMail. Requires valid MX DNS records to be configured beforehand.

```APIDOC
## mutation addDomain

### Description
Registers a personal domain to the user's identity. Requires MX records to point to mx.dropmail.me.

### Request Body
- **name** (String) - Required - The domain name to register.
- **adminPassword** (String) - Required - Password used for future domain management/deletion.

### Request Example
mutation {
  addDomain(input: {name: "example.com",
                    adminPassword: "my-secret-password"}) {
    id,
    name,
    availableVia
  }
}

### Response
#### Success Response (200)
- **id** (String) - Unique identifier for the domain.
- **name** (String) - The registered domain name.
- **availableVia** (List) - List of availability methods.

#### Response Example
{
  "data": {
    "addDomain": {
        "id": "RG9tYWluOjX=",
        "name": "example.com",
        "availableVia": ["API"]
      }
  }
}
```

--------------------------------

### MutationRoot API Endpoints

Source: https://dropmail.me/api/schema.graphql

Endpoints for creating, modifying, and deleting sessions, addresses, and domains.

```APIDOC
## POST /api/graphql/${AUTH_TOKEN}

### Description
Allows for mutations to create, update, and delete resources like sessions, addresses, and domains.

### Method
POST

### Endpoint
https://dropmail.me/api/graphql/${AUTH_TOKEN}

### Parameters
#### Request Body
- **query** (string) - Required - The GraphQL mutation string.
- **variables** (object) - Optional - Variables for the GraphQL mutation.

### Request Example
```json
{
  "query": "mutation { introduceSession { id, addresses { address } } }"
}
```

### Response
#### Success Response (200)
- **data** (object) - The result of the GraphQL mutation.
- **errors** (array) - An array of errors, if any occurred during mutation execution.
```

--------------------------------

### Query Available Domains

Source: https://dropmail.me/api

Use this GraphQL query to fetch a list of all available domains, their IDs, and availability information. IDs are static and can be cached.

```graphql
query {
    domains {
        id,
        name,
        availableVia,
        expiresAt
    }
}
    

```

--------------------------------

### Configure VS Code MCP

Source: https://dropmail.me/api

Define the DropMail server in the workspace MCP configuration file for VS Code.

```json
{
  "servers": {
    "dropmail": {
      "type": "stdio",
      "command": "dropmail-mcp",
      "env": {
        "DROPMAIL_TOKEN": "${input:dropmail-token}"
      }
    }
  },
  "inputs": [
    {
      "id": "dropmail-token",
      "type": "promptString",
      "description": "DropMail API token (obtain at dropmail.me/api/)",
      "password": true
    }
  ]
}
```

--------------------------------

### Query GraphQL API with Node.js

Source: https://dropmail.me/api

Implementation using the graphql-request library.

```javascript
// See https://github.com/prisma-labs/graphql-request
import { request, gql } from 'graphql-request'

async function main() {
  const token = ''
  const endpoint = 'https://dropmail.me/api/graphql/' + token

  const query = gql`
    query mailWithHtml($sanitizerConfig: HtmlSanitizerConfig) { sessions { mails { fromAddr headerSubject text sanitizedHtml(sanitizerConfig: $sanitizerConfig) } } }
  `
  const variables = {"sanitizerConfig":{"imgData":"keep","imgCid":"proxy","imgHttp":"keep"}}

  const data = await request(endpoint, query, variables)
  console.log(JSON.stringify(data, undefined, 2))
}
main().catch((error) => console.error(error))
```

--------------------------------

### Introduce Session Mutation

Source: https://dropmail.me/api

This mutation creates a new session with a random email address. It returns the session ID, expiration time, and the newly created email address. The session's lifetime is extended with each access.

```APIDOC
## POST /graphql

### Description
Creates a new session with a random email address. Returns the session ID, expiration time, and the new email address. The session's lifetime is extended with each access.

### Method
POST

### Endpoint
/graphql

### Request Body
```json
{
  "query": "mutation IntroduceSession($addresses: Int) { introduceSession(addresses: $addresses) { id, expiresAt, addresses { address } } }",
  "variables": {
    "addresses": 1
  }
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the session.
- **expiresAt** (string) - The timestamp when the session will expire.
- **addresses** (array) - A list of email addresses associated with the session.
  - **address** (string) - The email address.

#### Response Example
```json
{
  "data": {
    "introduceSession": {
      "id": "U2Vzc2lvbjqcMxamadJC_aLiPz_XL0lK",
      "expiresAt": "2021-02-18T04:20:00+00:00",
      "addresses": [
        {
          "address": "example@10mail.org"
        }
      ]
    }
  }
}
```
```

--------------------------------

### Query Domains

Source: https://dropmail.me/api

Retrieves a list of available domains for email address generation.

```APIDOC
## POST /graphql

### Description
Fetches all available domains, including their IDs, names, and expiration status.

### Method
POST

### Endpoint
/graphql

### Request Example
query {
    domains {
        id,
        name,
        availableVia,
        expiresAt
    }
}

### Response
#### Success Response (200)
- **data** (object) - Contains the list of domains.

#### Response Example
{
  "data": {
    "domains": [
      {
        "name": "dropmail.me",
        "id": "RG9tYWluOjE=",
        "availableVia": ["API", "TELEGRAM", "WEB"],
        "expiresAt": null
      }
    ]
  }
}
```

--------------------------------

### List all sessions via GraphQL

Source: https://dropmail.me/api

Retrieve all non-expired sessions and their mail details.

```json
{
  "query": "query {sessions {id, expiresAt, mails {rawSize, fromAddr, toAddr, downloadUrl, text, headerSubject}}}"
}
```

--------------------------------

### Subscribe to new emails

Source: https://dropmail.me/api

GraphQL subscription command to receive real-time notifications for new emails.

```graphql
subscription {
    sessionMailReceived(id: "U2Vzc2lvbjqcMxamadJC_aLiPz_XL0lK") {
        rawSize,
        fromAddr,
        toAddr,
        downloadUrl,
        text,
        headerSubject
    }
}
```

--------------------------------

### POST /graphql (Query)

Source: https://dropmail.me/api

Retrieves a list of emails for a specific session using GraphQL queries.

```APIDOC
## POST /graphql

### Description
Fetches up to 100 emails for a given session ID. Supports incremental fetching using the mailsAfterId field.

### Method
POST

### Endpoint
/graphql

### Request Body
- **query** (string) - Required - The GraphQL query string containing the session ID and requested mail fields.

### Request Example
{
  "query": "query { session(id: \"U2Vzc2lvbjqcMxamadJC_aLiPz_XL0lK\") { mails { rawSize, fromAddr, toAddr, downloadUrl, text, headerSubject } } }"
}

### Response
#### Success Response (200)
- **data** (object) - The requested session data containing a list of mail objects.

#### Response Example
{
  "data": {
    "session": {
      "mails": [
        {
          "toAddr": "example@10mail.org",
          "text": "Hello\r\n",
          "rawSize": 812,
          "headerSubject": "Hello",
          "fromAddr": "test@example.com",
          "downloadUrl": "https://dropmail.me/download/mail/gql:1:9c3316a6-69d2-42fd-a2e2-3f3fd72f494a/vb18co6tn6b4pv10hgr7lhaljcnrhvk5"
        }
      ]
    }
  }
}
```

--------------------------------

### List Domains cURL Request

Source: https://dropmail.me/api

Demonstrates how to use cURL to send a POST request to the Dropmail.me API for listing domains. This is useful for command-line testing.

```bash
curl https://dropmail.me/api/graphql/ -H 'Content-Type: application/json' \
 -d '{"query":"query {domains {id, name, introducedAt, expiresAt, availableVia}}"}'
```

--------------------------------

### SubscriptionRoot API Endpoints

Source: https://dropmail.me/api/schema.graphql

Endpoint for subscribing to real-time mail reception events.

```APIDOC
## POST /api/graphql/${AUTH_TOKEN}

### Description
Subscribes to receive new emails in real-time for a given session.

### Method
POST

### Endpoint
https://dropmail.me/api/graphql/${AUTH_TOKEN}

### Parameters
#### Request Body
- **query** (string) - Required - The GraphQL subscription string for `sessionMailReceived`.
- **variables** (object) - Required - Variables for the subscription, including `id` and optional `mailsAfterId`.

### Request Example
```json
{
  "query": "subscription { sessionMailReceived(id: \"session_id_here\", mailsAfterId: \"last_mail_id_here\") { id, from, subject, text, html, date } }"
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains the received mail object when new mail arrives.
- **errors** (array) - An array of errors, if any occurred during subscription setup or execution.
```

--------------------------------

### Authentication

Source: https://dropmail.me/api

Information on obtaining and using authentication tokens for the DropMail.me API.

```APIDOC
## Authentication

### Description
Authentication is handled via API tokens. Free `af_...` tokens are available without sign-up. Legacy tokens (any random string) are deprecated and will be rejected starting April 2026.

### Token Generation
Free tokens can be generated via the DropMail.me website. Different durations are available, some requiring a captcha.

### Token Usage
Tokens should be included in the `${AUTH_TOKEN}` placeholder in both HTTP and WebSocket endpoints.

### Deprecation Notice
- Using arbitrary strings as `${AUTH_TOKEN}` is deprecated.
- Tokens generated before April 5, 2026, are corrupted and must be replaced.
- Rate limits are stricter for legacy tokens.

### Renewing Tokens
Existing `af_...` tokens can be renewed to preserve their identity. A new token must be generated if it was issued before April 5, 2026.
```

--------------------------------

### HtmlSanitizerConfig Input

Source: https://dropmail.me/api/schema.graphql

Configuration options for sanitizing HTML content.

```APIDOC
## HtmlSanitizerConfig Input

### Description
Configuration object for the `sanitizedHtml` and `downloadSanitizedHtmlUrl` methods.

### Fields
- **imgData** (String) - Controls handling of `<img>` tags with `data:` URIs. Options: "strip", "keep". Default: "strip".
- **imgCid** (String) - Controls handling of `<img>` tags with `cid:` URIs. Options: "strip", "keep", "proxy". Default: "strip".
- **imgHttp** (String) - Controls handling of `<img>` tags with HTTP/HTTPS URIs. Options: "strip", "keep", "proxy". Default: "strip".
```
Tokens:
Raw