Request handle claim confirmation email
Initiates a handle claim. A confirmation email is sent to the destination address. The handle is only created after the token from the email is confirmed. Handles are permanent — once claimed, the name can never be reused, even after unsubscribe.
curl -X GET "https://mail.haltman.io/api/handle/subscribe?handle=example_string&to=user@example.com" \
-H "Content-Type: application/json"
import requests
import json
url = "https://mail.haltman.io/api/handle/subscribe?handle=example_string&to=user@example.com"
headers = {
"Content-Type": "application/json"
}
response = requests.get(url, headers=headers)
print(response.json())
const response = await fetch("https://mail.haltman.io/api/handle/subscribe?handle=example_string&to=user@example.com", {
method: "GET",
headers: {
"Content-Type": "application/json"
}
});
const data = await response.json();
console.log(data);
package main
import (
"fmt"
"net/http"
)
func main() {
req, err := http.NewRequest("GET", "https://mail.haltman.io/api/handle/subscribe?handle=example_string&to=user@example.com", nil)
if err != nil {
panic(err)
}
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
fmt.Println("Response Status:", resp.Status)
}
require 'net/http'
require 'json'
uri = URI('https://mail.haltman.io/api/handle/subscribe?handle=example_string&to=user@example.com')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri)
request['Content-Type'] = 'application/json'
response = http.request(request)
puts response.body
{
"ok": true,
"action": "handle_subscribe",
"handle": "example_string",
"to": "user@example.com",
"confirmation": {
"sent": true,
"ttl_minutes": 42,
"reason": "example_string"
}
}
{
"error": "example_string",
"field": "example_string",
"reason": "example_string",
"hint": "example_string",
"constraints": {}
}
{
"error": "example_string"
}
{
"error": "example_string",
"ban": {},
"type": "example_string",
"value": "example_string"
}
{
"error": "Conflict",
"message": "The request conflicts with the current state of the resource",
"code": 409,
"details": "Resource already exists"
}
{
"error": "example_string",
"where": "example_string",
"reason": "example_string"
}
{
"error": "Internal Server Error",
"message": "An unexpected error occurred on the server",
"code": 500,
"requestId": "req_1234567890"
}
GET
/api/handle/subscribe
GET
query
handlestring
RequiredThe local-part to claim. Must be a valid RFC 5322 dot-atom local-part.
Max length: 64 • Pattern: ^[a-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&'*+/=?^_`{|}~-]+)*$
query
tostring
RequiredDestination email address where all handle mail will be forwarded.
Format: email
Request Preview
Response
Response will appear here after sending the request
Query Parameters
handlestring
RequiredThe local-part to claim. Must be a valid RFC 5322 dot-atom local-part.
tostring
RequiredDestination email address where all handle mail will be forwarded.
Responses
okboolean
Requiredactionstring
RequiredAllowed values:
handle_subscribehandlestring
Requiredtostring
Requiredconfirmationobject
Requiredsentboolean
Requiredttl_minutesinteger
Requiredreasonstring
Present when the confirmation was not sent (e.g. "cooldown").
errorstring
Requiredfieldstring
reasonstring
hintstring
constraintsobject
errorstring
Requirederrorstring
Requiredbanobject
typestring
valuestring
errorstring
Requirederrorstring
Requiredwherestring
reasonstring
errorstring
RequiredWas this page helpful?
Last updated Apr 9, 2026
Built with Documentation.AI