REST API · v1

Send email with GridInbox.

Use your GridInbox API key to send from a verified mailbox or alias, read messages, and automate inbox workflows from your application.

Yes, sending is supported. The endpoint is POST /api/v1/messages/send. The current API-key authentication error caused by a missing Tenant.role column has been fixed.

Quickstart

Generate an API key in GridInbox under Settings → Developer, then send a test message. Keep the key server-side and never expose it in browser code.

curl -X POST https://api.gridinbox.com/api/v1/messages/send \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": ["[email protected]"],
    "subject": "Hello from GridInbox",
    "content": "<p>This message was sent through the GridInbox API.</p>"
  }'

Authentication

Send the API key in the standard Bearer authorization header.

Authorization: Bearer sk_live_...

API keys are tenant-scoped. Requests can only send from mailboxes and aliases belonging to the same tenant. Rotate a compromised key immediately in Settings → Developer.

Read messages

API keys can read all mailboxes in their tenant, including messages delivered through valid aliases. Add mailboxId to narrow a request to one mailbox; omitting it queries the full tenant scope.

List messages

GET/api/v1/messages

Query parameters: mailboxId, folder, q, start_date, end_date, has_attachments, otp_only, query_all_except_spam, limit, and offset.

curl "https://api.gridinbox.com/api/v1/messages?mailboxId=MAILBOX_ID&folder=INBOX" -H "Authorization: Bearer sk_live_..."

The response contains data.messages and data.total.

Get message details

GET/api/v1/messages/:id

Returns message metadata, parsed content, recipients, labels, and attachment metadata. Use the optional mailboxId query parameter when needed.

Get raw message

GET/api/v1/messages/:id/raw

Returns the stored raw message. Add download=true to receive it as an RFC 822 download.

Folder statistics

GET/api/v1/messages/stats

Returns message counts by folder. The optional mailboxId parameter selects a mailbox.

Extract OTP codes

GET/api/v1/messages/latest-otp

Returns the latest parsed one-time password for an accessible mailbox. Query parameters: alias (recipient alias or address), since (ISO 8601 timestamp), and timeout (a short polling window subject to a tenant- and risk-aware maximum).

curl "https://api.gridinbox.com/api/v1/messages/[email protected]" -H "Authorization: Bearer sk_live_..."

When no matching code is found, the API returns 404.

Attachments

Upload an attachment

POST/api/v1/attachments/upload

Use multipart/form-data with a file field. The response returns an attachment object that can be passed in the send request’s attachments array.

curl -X POST https://api.gridinbox.com/api/v1/attachments/upload -H "Authorization: Bearer sk_live_..." -F "[email protected]"

Preview an uploaded object

GET/api/v1/attachments/proxy?key=ATTACHMENT_KEY

Streams an attachment belonging to the current tenant. The key is returned by the upload endpoint.

Create a signed download link

POST/api/v1/attachments/:id/link

Returns a short-lived signed URL. Send {"preview":true} to request inline preview behavior.

Download an attachment

GET/api/v1/attachments/:id

Streams an attachment after tenant and mailbox authorization. The signed-link flow is recommended for browser downloads.

Send an email

POSThttps://api.gridinbox.com/api/v1/messages/send

Creates and sends an email, then stores a copy in the sender mailbox’s Sent folder.

Request body

Field	Type	Required	Description
`from`	string	Yes	Verified mailbox or alias address owned by the tenant.
`to`	string \| string[]	Yes	One or more recipient addresses. Comma and semicolon separated strings are accepted.
`subject`	string	Yes	Message subject.
`content`	string	Yes	HTML message body. Plain text is also accepted.
`cc`	string \| string[]	No	Carbon-copy recipients.
`bcc`	string \| string[]	No	Blind carbon-copy recipients.
`attachments`	object[]	No	Previously uploaded attachment objects containing `r2Key`, `filename`, `contentType`, and `size`.
`inReplyTo`	string	No	Message-ID used to thread a reply.
`references`	string[]	No	Message-ID references used for threading.

Successful response

{
  "success": true,
  "messageId": "2c5c7d9e-..."
}

Responses & errors

Status	Meaning
`200`	Email accepted and stored in Sent.
`400`	Required field missing or request data invalid.
`401`	API key missing or invalid.
`403`	The sender address is not accessible to this tenant.
`429`	Rate or daily sending limit exceeded.
`500`	Provider or server error. Retry with backoff when appropriate.

{
  "success": false,
  "error": "Sender address not found or access denied"
}

Limits and deliverability

API requests, uploads, message volume, and request sizes are subject to platform safeguards. Limits are dynamically adjusted based on your tenant, plan, usage patterns, traffic risk, and account status. When a limit is reached, the API returns a rate-limit response; use exponential backoff and retry only when appropriate.

Your plan quota, verified-domain status, and sender permissions also apply. Use a verified domain and a sender address that exists in your GridInbox tenant. Do not send unsolicited or abusive content; repeated bounces and complaints may suspend sending.

API Key scope and audit

API keys are designed for tenant-scoped automation. They support message reading, OTP extraction, statistics, sending, and attachment workflows. Administrative actions, billing, team management, mailbox management, domain management, drafts, and message mutations require a user session token and are not available through an API key.

Every authenticated API-key request is recorded in the tenant API audit log with method, path, status, source IP, and success state. Request bodies and authorization headers are never stored in the audit record.

Need help? Contact [email protected].