API Documentation

Effective 8 October 2026 · Version 1.0

Reference for the live Indo Mail HTTP API at https://indoemail.in: sign-in including the 2-step flow, conventions, routes by area, curl examples, and the planned versioned API and API keys.

1. Status and scope

The Indo Mail web and Android apps are built on a JSON API served from https://indoemail.in. You can call the same API from your own scripts to work with your own account. This is a first-party API. It is live, but it is not yet a public developer product: there is no developer portal, no API keys, no OAuth for third-party apps, no webhooks and no official SDK yet. Those are described as Planned at the end of this page.

Because the API is shared with our own apps, routes can change as the apps change. We will tell developers who have early access (see the Developer Portal document) before breaking changes. Use the API only for your own account, or for accounts whose owners have asked you to.

2. Conventions

Base URL: https://indoemail.in. HTTPS only (TLS 1.2 or 1.3).
Format: requests and responses are JSON (Content-Type: application/json), except for file uploads, which use multipart/form-data, and file downloads.
Authentication: send Authorization: Bearer <token> on every call except the public routes.
Errors: a failed call returns an HTTP status code and a body like {"error":"Wrong email or password."}. The text is written to be shown to a person.
Status codes: 200 and 201 for success, 400 for a bad request, 401 for missing or wrong credentials, 403 for no permission, 404 for not found, 413 for a body that is too large, 429 for a limit reached.
Money: amounts in requests and responses are in rupees (for example 250.00). Ad budgets and prices are checked in rupees too.
Times: timestamps from the API are in UTC, and sign-in history times end in Z.
Rate limits: sign-in, sign-up, the second sign-in step and password change are limited to 20 attempts per 15 minutes per client. A message is limited to 100 recipients, and an account can send to 500 recipients in any 24 hours. Responses to limited routes include standard RateLimit headers.
Size limits: one message with attachments up to 25 MB; up to 20 files per request; Drive files up to 5 GB by multipart upload.
CORS: the API is meant for your own scripts and servers. Only the public advertising and Tag Manager routes send open cross-origin headers.

3. Authentication

Sign in with your address (or username) and password. The reply contains a bearer token that lasts 7 days. Store it like a password.

If you have turned on 2-Step Verification, the first call does not return a token. It returns {"twoFactor":true,"ticket":"..."}. The ticket is valid for 5 minutes. Send it to the second step with the six-digit code from your authenticator app, and you receive the token and your user record.

Route	Body	Reply
POST /api/auth/login	login, password	token and user, or twoFactor and ticket
POST /api/auth/login/2fa	ticket, code	token and user
POST /api/auth/2fa/setup	none (signed in)	secret and otpauthUrl for the authenticator app
POST /api/auth/2fa/enable	code	ok and the updated user
POST /api/auth/2fa/disable	password	ok and the updated user
GET /api/auth/activity	none	your last 50 sign-in events: event, ip, device, at
GET /api/auth/me	none	your user record
PATCH /api/auth/me	displayName, signature, recoveryEmail, phone	updated user
POST /api/auth/change-password	currentPassword, newPassword	ok
POST /api/auth/register	username, password, displayName, phone, recoveryEmail (optional)	token and user (201)
POST /api/auth/register-business	orgName, domain, username, password, displayName, phone, recoveryEmail (optional)	token and user for the first administrator (201)

Public helpers: GET /api/auth/config, GET /api/auth/check-username?u=&domain= and GET /api/auth/check-domain?d=. A mobile number is required at sign-up. A token stops working when the account is disabled or its business domain is suspended.

4. Mail

All routes are under /api/mail and need a token.

Route	Purpose
GET /messages	List conversations. Query: folder (inbox, starred, sent, drafts, archive, all, spam, trash, or label:ID), q (search with operators such as from:, has:attachment, is:unread), limit (up to 100), page.
GET /threads/:threadId	Open a conversation and mark it read.
GET /messages/:id	Read one message.
PATCH /messages/:id	Change one message: isRead, isStarred, or an action (with labelId for labels).
POST /threads/action	Act on conversations: threadIds, action (read, unread, star, unstar, archive, inbox, spam, notspam, trash, restore, delete, label, unlabel) and folder.
POST /folders/:folder/empty	Empty Trash or Spam.
GET /counts	Unread and total counts for the folder list.
POST /drafts	Create or update a draft: to, cc, bcc, subject, html, draftId, inReplyToId.
POST /send	Send a message (multipart). See section 8.
GET /labels, POST /labels, PATCH /labels/:id, DELETE /labels/:id	Manage coloured labels: name and a colour such as #0061FD.
GET /contacts?q=	Suggest addresses while composing.
GET /attachments/:id	Download an attachment with your token.
GET /attachments/:id/link	Get a signed, short-lived download link.
GET /download/:id?dl=	Download with a signed link. No token needed while the link is valid.
POST /events-ticket and GET /events	Get a 60-second ticket and open the live stream of new-mail events.

5. Drive, Photos and Cloud

Routes are under /api/drive. Folders and files belong to a space (drive, photos or vault), and the space field chooses it for top-level items.

Route	Purpose
GET /usage	Storage used and your allowance.
GET /items	List items in a folder or space.
POST /folders	Create a folder: name, parentId, space.
POST /upload	Upload up to 20 files (multipart field `files`) with optional parentId and space.
GET /config	Whether large uploads are available.
POST /uploads, POST /uploads/:id/parts, POST /uploads/:id/complete, DELETE /uploads/:id	Large file upload in parts directly to Amazon S3, up to 5 GB. Parts are 64 MB.
POST /from-attachment/:attId	Save a mail attachment into Drive.
GET /items/:id/content, GET /items/:id/link	Download a file, or get a signed link.
PATCH /items/:id, DELETE /items/:id, POST /trash/empty	Rename, move, delete and empty trash.
GET /albums, POST /albums, GET /albums/:id, POST /albums/:id/items, DELETE /albums/:id	Photo albums.
GET /attachments	Files that arrived as mail attachments.

6. Other apps

Under /api/apps: contacts (GET, POST, PUT /contacts/:id, DELETE, GET /contacts.vcf, POST /contacts/import); Maps (GET /maps/config, /maps/search, /maps/places, POST and DELETE saved places); Translate (GET /translate/languages, POST /translate, GET and DELETE /translate/history; 34 languages); Wallet (GET /wallet, PUT /wallet/settings, POST /wallet/requests, PATCH /wallet/requests/:id); Travel (trips and items, GET /travel/detected); Business Profile (GET and PUT /profile).

7. Business, admin, advertising and push

These areas need the right role.

Area	Routes	Who can call
Company admin (/api/business)	GET and PATCH /domain, POST /domain/verify (live DNS check), GET and POST /users, PATCH /users/:id	Administrators of a company domain
Indo Mail admin (/api/admin)	GET /stats, GET and POST /users, PATCH /users/:id, GET /domains, PATCH /domains/:id, GET /queue, GET /customers, GET /customers.csv, GET /customers/:id/activity, POST /reports/monthly	Indo Mail administrators only
Ads (/api/ads)	GET and PUT /advertiser; campaigns (GET, POST, PATCH, DELETE) and POST /campaigns/:id/creatives; GET /leads; GET /reports?days=; merchant and manufacturer products; tag containers and tags; GET /eligible	Signed-in advertisers
Ad review (/api/ads/review)	GET /review, POST /review/:id	Indo Mail administrators
Push (/api/push)	GET /key, POST /subscribe, POST /unsubscribe, GET /devices, POST /test, device routes for the Android app	Signed-in users; GET /key is public

Public routes that need no token: GET /api/ads/serve, GET /api/network/ads, GET /a/:id, POST /api/ads/leads/:creativeId, GET /t/:pid.js, POST /t/:pid/collect, GET /healthz, GET /api/ops/status.

8. Examples

Replace the address and password with your own. The examples use jq to read the token.

Sign in: curl -s https://indoemail.in/api/auth/login -H 'Content-Type: application/json' -d '{"login":"you@indoemail.in","password":"my-long-passphrase"}'
Sign in with 2-Step Verification: if the reply has twoFactor, keep its ticket in the shell variable TICKET and run curl -s https://indoemail.in/api/auth/login/2fa -H 'Content-Type: application/json' -d "{\"ticket\":\"$TICKET\",\"code\":\"123456\"}"
Keep the token: TOKEN=$(curl -s https://indoemail.in/api/auth/login -H 'Content-Type: application/json' -d '{"login":"you@indoemail.in","password":"my-long-passphrase"}' | jq -r .token)
Read the inbox: curl -s 'https://indoemail.in/api/mail/messages?folder=inbox&;limit=20' -H "Authorization: Bearer $TOKEN"
Search unread mail with attachments: curl -s -G https://indoemail.in/api/mail/messages -H "Authorization: Bearer $TOKEN" --data-urlencode 'q=is:unread has:attachment'
Send a message with an attachment (multipart): curl -s https://indoemail.in/api/mail/send -H "Authorization: Bearer $TOKEN" -F to=friend@indoemail.in -F subject='Report' -F html='<p>Hello, the report is attached.</p>' -F attachments=@report.pdf. Separate several recipients with commas in to, cc and bcc. To reply in the same conversation, add -F inReplyToId=4812.
Upload a file to Drive: curl -s https://indoemail.in/api/drive/upload -H "Authorization: Bearer $TOKEN" -F files=@photo.jpg
Create a UPI payment request (after setting your UPI ID with PUT /api/apps/wallet/settings): curl -s https://indoemail.in/api/apps/wallet/requests -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{"direction":"receive","counterparty":"Asha","amount":250,"note":"Invoice 118"}'. The reply includes a upiLink that the payer opens in their UPI app. The amount can be between ₹1 and ₹1,00,000.
Check a company domain's DNS: curl -s -X POST https://indoemail.in/api/business/domain/verify -H "Authorization: Bearer $TOKEN"

9. Good practice

Never put your password or token in a public repository, a web page or a shared script.
Sign in once and reuse the token for its 7 days, instead of signing in for every call.
Handle 401 by signing in again, and 429 by waiting and retrying later.
Do not poll in a tight loop. For new mail, use the live stream or Web Push (see the Webhooks document).
Do not use the API to send spam, harvest addresses or scrape other people's data. Our Acceptable Use rules apply.

10. Planned: versioned API and API keys

Planned, not live. We intend to publish a stable, versioned API under /api/v2 for third-party developers, with a deprecation notice of at least 12 months for breaking changes. We also plan API keys with fixed scopes that can be created and revoked in Settings, so that scripts do not have to use your password. These will sit beside the planned OAuth 2.0 sign-in (see the OAuth Authentication document) and webhooks. Dates are not fixed. Routes described above under /api will keep working until /api/v2 is released and for the notice period after that.

11. Contact

Developer questions and early access: contact@indoemail.in with the subject "Developer access". Security issues in the API: security@indoemail.in.

INDO CHATS PRIVATE LIMITED, 168, GT Rd, near Aloka Cinema, Shibpur, Howrah, West Bengal 711102, India.