API reference
Messages, drafts and labels in Pinal Mail.
Base URL https://api.pinal.tech/v1
API reference
Messages, drafts and labels in Pinal Mail.
Base URL https://api.pinal.tech/v1
/mail/messagesMessages in a mailbox, newest first. With only mail.metadata, bodies and attachments are omitted.
label string Filter by label ID.
q string Search query, same syntax as Picacho's search bar.
limit integer Items per page, 1–100.
cursor string Opaque cursor from a previous page's next_cursor.
curl "https://api.pinal.tech/v1/mail/messages?label=inbox&q=from%3Asam%20has%3Aattachment" \
-H "Authorization: Bearer $ACCESS_TOKEN"{
"messages": [
{
"id": "msg_8f2c41",
"thread_id": "string",
"from": {
"name": "string",
"email": "alex@pinal.email"
},
"to": [
{
"name": "string",
"email": "alex@pinal.email"
}
],
"cc": [
{
"name": "string",
"email": "alex@pinal.email"
}
],
"subject": "string",
"snippet": "string",
"text": "string",
"html": "string",
"labels": [
"string"
],
"read": true,
"attachments": [
{
"id": "string",
"filename": "string",
"size": 0,
"content_type": "string"
}
],
"date": "2026-11-19T15:20:04Z"
}
],
"next_cursor": "string"
}/mail/messagesSends immediately from the person's primary address. Flagged as a sensitive action on the consent screen.
to array of Address required cc array of Address bcc array of Address subject string required text string html string in_reply_to string Message ID to reply to.
curl -X POST "https://api.pinal.tech/v1/mail/messages" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"to": [
{
"email": "sam@example.com"
}
],
"subject": "Trail map",
"text": "Here's the route for Saturday."
}'{
"id": "msg_8f2c41",
"thread_id": "string",
"from": {
"name": "string",
"email": "alex@pinal.email"
},
"to": [
{
"name": "string",
"email": "alex@pinal.email"
}
],
"cc": [
{
"name": "string",
"email": "alex@pinal.email"
}
],
"subject": "string",
"snippet": "string",
"text": "string",
"html": "string",
"labels": [
"string"
],
"read": true,
"attachments": [
{
"id": "string",
"filename": "string",
"size": 0,
"content_type": "string"
}
],
"date": "2026-11-19T15:20:04Z"
}/mail/messages/{id}One message with its body and attachment list.
id string requiredMessage ID.
curl "https://api.pinal.tech/v1/mail/messages/{id}" \
-H "Authorization: Bearer $ACCESS_TOKEN"{
"id": "msg_8f2c41",
"thread_id": "string",
"from": {
"name": "string",
"email": "alex@pinal.email"
},
"to": [
{
"name": "string",
"email": "alex@pinal.email"
}
],
"cc": [
{
"name": "string",
"email": "alex@pinal.email"
}
],
"subject": "string",
"snippet": "string",
"text": "string",
"html": "string",
"labels": [
"string"
],
"read": true,
"attachments": [
{
"id": "string",
"filename": "string",
"size": 0,
"content_type": "string"
}
],
"date": "2026-11-19T15:20:04Z"
}/mail/messages/{id}Add or remove labels, or mark read/unread.
id string requiredMessage ID.
add_labels array of string remove_labels array of string read boolean curl -X PATCH "https://api.pinal.tech/v1/mail/messages/{id}" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"add_labels": [
"string"
],
"remove_labels": [
"string"
],
"read": true
}'{
"id": "msg_8f2c41",
"thread_id": "string",
"from": {
"name": "string",
"email": "alex@pinal.email"
},
"to": [
{
"name": "string",
"email": "alex@pinal.email"
}
],
"cc": [
{
"name": "string",
"email": "alex@pinal.email"
}
],
"subject": "string",
"snippet": "string",
"text": "string",
"html": "string",
"labels": [
"string"
],
"read": true,
"attachments": [
{
"id": "string",
"filename": "string",
"size": 0,
"content_type": "string"
}
],
"date": "2026-11-19T15:20:04Z"
}/mail/draftsSaves a draft the person can review and send from their mail app.
to array of Address required cc array of Address bcc array of Address subject string required text string html string in_reply_to string Message ID to reply to.
curl -X POST "https://api.pinal.tech/v1/mail/drafts" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"to": [
{
"name": "string",
"email": "alex@pinal.email"
}
],
"cc": [
{
"name": "string",
"email": "alex@pinal.email"
}
],
"bcc": [
{
"name": "string",
"email": "alex@pinal.email"
}
],
"subject": "string",
"text": "string",
"html": "string",
"in_reply_to": "string"
}'{
"id": "msg_8f2c41",
"thread_id": "string",
"from": {
"name": "string",
"email": "alex@pinal.email"
},
"to": [
{
"name": "string",
"email": "alex@pinal.email"
}
],
"cc": [
{
"name": "string",
"email": "alex@pinal.email"
}
],
"subject": "string",
"snippet": "string",
"text": "string",
"html": "string",
"labels": [
"string"
],
"read": true,
"attachments": [
{
"id": "string",
"filename": "string",
"size": 0,
"content_type": "string"
}
],
"date": "2026-11-19T15:20:04Z"
}curl "https://api.pinal.tech/v1/mail/labels" \
-H "Authorization: Bearer $ACCESS_TOKEN"{
"labels": [
{
"id": "inbox",
"name": "string",
"system": true,
"unread": 0,
"color": "string"
}
]
}