MailAPI reference
Base URL https://mailapi.pushkarsingh4343.workers.dev. All responses are JSON. MailAPI is open source: github.com/nullstacks/mailapi.
Authentication
Send your key as Authorization: Bearer YOUR_KEY (or the X-API-Key header). Sign in at /auth/login; the dashboard shows your gmk_… key. One key works for every linked account.
Accounts
Link more Gmail accounts on the dashboard. One key reaches every linked mailbox and they are all live at the same time: pick the mailbox per request with email. If you leave it out, the key's own account is used.
| Endpoint | Description |
|---|---|
GET/v1/me | Key owner and linked accounts |
GET/v1/accounts | All linked accounts and the default |
POST/v1/key/rotate | Rotate your key (the old one dies) |
DELETE/v1/account?email=… | Revoke Google access and delete that account's data |
Addresses & temp mail
Gmail ignores dots and anything after +: p.i.us+news@gmail.com is the same inbox as pius@gmail.com. Free disposable email: one inbox, unlimited addresses. Pass any address as email and it is detected for you: a linked address returns that whole inbox, a +tag or dot variant returns only mail addressed to it. There is no separate alias endpoint or key.
| Request | Result |
|---|---|
GET/v1/messages?email=you@gmail.com | The whole inbox of that linked account |
GET/v1/messages?email=you+netflix@gmail.com | Only mail addressed to that alias |
POST/v1/messages/send | Send from any linked address or alias: "from":"you+shop@gmail.com" |
# two accounts and a temp alias, same key, all at once
curl -H "Authorization: Bearer $KEY" "https://mailapi.pushkarsingh4343.workers.dev/v1/messages?email=a%40gmail.com" &
curl -H "Authorization: Bearer $KEY" "https://mailapi.pushkarsingh4343.workers.dev/v1/messages?email=b%40gmail.com" &
curl -H "Authorization: Bearer $KEY" "https://mailapi.pushkarsingh4343.workers.dev/v1/messages?email=a%2Bnetflix%40gmail.com&maxResults=5" &
waitMessages
Every route below also takes ?email= to choose the mailbox (message and thread ids belong to one account, so pass the same address you listed with).
| Endpoint | Description |
|---|---|
GET/v1/messages | List. Params: email, q (Gmail search), maxResults (≤50), pageToken, labelIds, ids_only=1 |
GET/v1/messages/:id | Parsed message: text, html, headers, attachments. ?raw=1 for the full Gmail payload |
GET/v1/messages/:id/attachments/:attId | Binary download (filename=, type= optional) |
POST/v1/messages/send | {to, cc?, bcc?, subject, text?, html?, attachments?:[{filename, contentType, content}], from?, threadId?} |
POST/v1/messages/:id/modify | {"addLabelIds":[],"removeLabelIds":[]} |
POST/v1/messages/:id/trash | Move to trash. /untrash moves it back |
GET/v1/threads/:id | Whole thread, parsed |
GET/v1/labels | All labels |
ANY/v1/gmail/* | Raw passthrough to the Gmail REST API (/v1/gmail/drafts, /v1/gmail/history …) |
curl -H "Authorization: Bearer $KEY" \
"https://mailapi.pushkarsingh4343.workers.dev/v1/messages?q=is:unread&maxResults=5"
curl -X POST "https://mailapi.pushkarsingh4343.workers.dev/v1/messages/send" \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"to":"friend@example.com","subject":"Hi","text":"sent via my API"}'Errors
| Status | Meaning |
|---|---|
401 | Bad or missing key, or the Google grant expired (the message says “Re-authorize”: sign in again) |
404 | Unknown route or id, or an email that isn't a linked account or an alias of one |
429 | Upstream Gmail quota |