API Reference

A REST API for reading, sending, and managing emails programmatically. Works great from Python scripts, bots, automations, or any HTTP client.

from vantixmail import VantixMail

mail = VantixMail("vmx_your_key_here")

# Read inbox
for msg in mail.inbox():
    print(msg["from"], "—", msg["subject"])

# Read unread only
for msg in mail.unread():
    body = mail.get_message(msg["uid"])
    print(body["body_text"])

# Send
mail.send("friend@gmail.com", "Hello", "Message body here.")

# If your key is invalid or revoked, a Windows dialog
# pops up automatically explaining what went wrong.Copy

Introduction

All requests and responses use JSON. Send Content-Type: application/json on POST requests. Every endpoint returns an error key on failure.

Authentication

Include your API key as a Bearer token on every request:

Authorization: Bearer vmx_your_api_key_hereCopy

Keys start with vmx_. They are only shown once when created — store them in an environment variable, not in source code.

Errors

The API uses standard HTTP status codes. Error responses always include an error field:

{
  "error": "Invalid API key"
}Copy

Common codes: 200 OK   400 Bad request   401 Unauthorized   404 Not found   500 Server error

Quickstart

Get running in two minutes with Python.

Install

pip install requestsCopy

Create a key, then use it

import requests

# 1. Create a key once (do this manually, save the result)
r = requests.post("https://vantixmail.xyz/api/v1/keys", json={
    "email":    "you@vantixmail.xyz",
    "password": "your_password",
    "label":    "my script"
})
API_KEY = r.json()["key"]   # vmx_abc123...  save this

# 2. Use it in all future requests
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
BASE    = "https://vantixmail.xyz/api/v1"

# Read your inbox
inbox = requests.get(f"{BASE}/messages", headers=HEADERS).json()
for msg in inbox["messages"]:
    print(msg["from"], "—", msg["subject"])

# Send an email
requests.post(f"{BASE}/send", headers=HEADERS, json={
    "to":      "someone@gmail.com",
    "subject": "Hello from Python",
    "body":    "This was sent via the VantixMail API."
})Copy

Create an API key

Verify ownership with your email and password. The key is shown once in the response — save it.

requests.post("https://vantixmail.xyz/api/v1/keys", json={
    "email":    "you@vantixmail.xyz",
    "password": "your_password",
    "label":    "automation"
})

# Response:
# {
#   "ok": true,
#   "key": "vmx_4b8f3a...",
#   "email": "you@vantixmail.xyz",
#   "label": "automation",
#   "created": "2025-06-04T17:00:00.000Z"
# }Copy

List API keys

Returns your existing keys. The key values are truncated for security.

requests.get(f"{BASE}/keys", headers=HEADERS).json()

# {"keys": [{"key": "vmx_4b8f3a...", "label": "automation", "created": "..."}]}Copy

Revoke an API key

requests.delete(f"{BASE}/keys/vmx_4b8f3a...", headers=HEADERS)
# {"ok": true}Copy

List messages

Returns up to 30 messages per page, newest first.

data = requests.get(f"{BASE}/messages", headers=HEADERS, params={
    "folder": "INBOX",
    "page":   1
}).json()

for msg in data["messages"]:
    read = "read" if msg["read"] else "unread"
    print(f"[{read}] uid={msg['uid']} from={msg['from_address']}")
    print(f"  subject: {msg['subject']}")
    print(f"  date:    {msg['date']}")
    print()Copy

Get a message

Fetches the full message including body text and HTML. Also marks it as read.

msg = requests.get(f"{BASE}/messages/42", headers=HEADERS, params={
    "folder": "INBOX"
}).json()

print(msg["subject"])
print(msg["from"])
print(msg["body_text"])       # plain text
# msg["body_html"] is also available if the email has HTMLCopy

Delete a message

requests.delete(f"{BASE}/messages/42", headers=HEADERS, params={
    "folder": "INBOX"
})
# {"ok": true}Copy

Send an email

Sends from your account. A copy is automatically saved to your Sent folder.

requests.post(f"{BASE}/send", headers=HEADERS, json={
    "to":      "friend@gmail.com",
    "subject": "Daily report",
    "body":    "Here's your summary for today.\n\nAll clear."
})
# {"ok": true}Copy

Verify a key

Returns the account linked to the current key. Use this to check if a key is still valid.

requests.get(f"{BASE}/me", headers=HEADERS).json()
# {"email": "you@vantixmail.xyz", "label": "my script"}Copy