Gmail

These endpoints send a one-to-one email to a contact through Gmail, from a mailbox you connected to Pathbound. You can send now, schedule a send up to 30 days ahead, or save a draft and send it later. Every email that goes out is recorded on the contact’s timeline.

A draft or a scheduled email is held by Pathbound, not by Gmail. It does not appear in Gmail until it is sent, and you review it through this API.

Three things have to be in place first: an API key with the actions:write scope, a Gmail mailbox connected by the user who created that key, and sending switched on for that mailbox by a workspace admin. Before you send explains each. The MCP tools gmail_send_email, gmail_create_draft, gmail_send_draft, gmail_list_outbox and gmail_cancel_outbox_email call the same endpoints: see MCP tools.

The scope. Every endpoint on this page needs actions:write. It is opt-in: a key holds it only when it was selected for that key. See Scopes.

The mailbox is your own. An API key acts as the user who created it, and sends only from Gmail mailboxes that user connected. A teammate’s mailbox is never listed and never usable. Connecting a mailbox takes a workspace admin, under Integrations → Gmail in the dashboard, so create the key as an admin who has connected one. An admin can connect a default mailbox and up to five more.

The mailbox can send. A mailbox sends when all three of these hold:

1. Its connection is valid.
2. Its Google permission includes sending (gmail.send).
3. A workspace admin has turned on Allow agents to send from this mailbox for it on the Gmail page. The switch is per mailbox and is off until an admin turns it on.

The API checks all three on every request that sends, schedules or saves an email, and again when a scheduled email goes out. The switch applies to every caller: an API key is held to it exactly as an AI agent is. Listing your senders, listing the outbox and canceling an email do not need it.

from names the mailbox, by its address. It has to be one of your own connected mailboxes.

Without from, Pathbound chooses in this order:

1. Your default mailbox, if it can send.
2. Otherwise, the only one of your mailboxes that can send.
3. If several can send and none of them is the default, the request is refused with SENDER_REQUIRED and you have to pass from.

If none of your mailboxes can send, the request is refused with the reason your default mailbox cannot.

A mailbox you name is used or refused. It is never swapped for another one. The same holds for a draft or a scheduled email: the mailbox is fixed when the email is created, and the email goes out from that mailbox or not at all.

These answers come from every endpoint that sends, schedules or saves an email. Each carries available_senders, the addresses you can send from right now, and a hint.

{
  "status": "error",
  "error": "Several of your Gmail mailboxes can send and none is the default: pass from",
  "code": "SENDER_REQUIRED",
  "available_senders": ["[email protected]", "[email protected]"],
  "hint": "Pass from as one of available_senders (GET /v1/integrations/gmail/senders lists your mailboxes)."
}

GET /v1/integrations/gmail/senders

Required scope: actions:write

Returns the Gmail mailboxes you connected and whether each one can send. Call it to choose a value for from.

curl https://api.pathbound.ai/v1/integrations/gmail/senders \
  -H "Authorization: Bearer $PATHBOUND_API_KEY"

{
  "status": "success",
  "senders": [
    { "email": "[email protected]", "is_default": true, "send_enabled": true },
    { "email": "[email protected]", "is_default": false, "send_enabled": false, "reason": "tool_disabled" }
  ],
  "default_sender": "[email protected]"
}

POST /v1/contacts/:contact_id/send_email

Required scope: actions:write

Sends one email to a contact, now. The recipient is the address on the contact record: no field of the request names one.

This endpoint only sends now. A request that carries send_at or draft is refused with 400 USE_OUTBOX and nothing is sent: use the outbox for those.

curl -X POST https://api.pathbound.ai/v1/contacts/665f1c2ab3d4e5f601234567/send_email \
  -H "Authorization: Bearer $PATHBOUND_API_KEY" \
  -H "Idempotency-Key: 7c1f0d5e-3b0a-4a3e-9a51-2f6f6e0f8f11" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "subject": "Next steps after the pilot",
    "body": "<p>Hi Ada,</p><p>Here is the plan we talked about.</p>"
  }'

{
  "status": "success",
  "action_id": "670bd0e4a1b2c3d4e5f60718",
  "message_id": "19286f3a7c2d4e10",
  "thread_id": "19286f3a7c2d4e10",
  "sent_at": "2026-10-13T14:02:11.482Z",
  "sender": "[email protected]"
}

The send appears on the contact’s timeline as a pathbound_action event with data.action_type set to gmail_send_email.

To reply inside an existing conversation, pass its thread_id. GET /v1/contacts/:contact_id/email-threads lists a contact’s Gmail threads with their ids.

A Gmail thread belongs to one mailbox, so the reply has to go out from the mailbox that holds the thread. A thread_id from another mailbox is refused with 422 THREAD_NOT_IN_MAILBOX and nothing is sent.

Idempotency-Key is what keeps a retry from becoming a second email. For 24 hours, a request with a key you have already used is answered like this:

The general rules are under Idempotency.

Delivery is at most once. Pathbound hands an email to Gmail one time, and never resends one whose outcome it does not know.

When Gmail takes the request and then gives no clear answer (a timeout, a dropped connection, a server error after the email was handed over), the email may or may not have gone out. The answer is 502 with the code SEND_UNCONFIRMED:

{
  "status": "error",
  "error": "Gmail did not answer; the email may have been sent",
  "code": "SEND_UNCONFIRMED",
  "action_id": "670bd0e4a1b2c3d4e5f60718",
  "sender": "[email protected]",
  "hint": "Check the Sent folder of [email protected] before sending again. Do not retry this request; to send deliberately, use a new Idempotency-Key."
}

What to do with it:

1. Do not retry automatically. The same request with the same Idempotency-Key gets SEND_UNCONFIRMED again for 24 hours and sends nothing.
2. Look in the Sent folder of the sender mailbox.
3. If the email is not there and you still want it sent, send it again under a new Idempotency-Key.

GMAIL_SEND_FAILED is the other 502 and means the opposite: nothing was sent, and a retry with the same key is safe. It carries retry_after_seconds. SEND_UNCONFIRMED never does.

A draft or a scheduled email whose send got no answer ends with status: "failed" and failure.code: "SEND_UNCONFIRMED". It is not sent again.

POST /v1/integrations/gmail/outbox

Required scope: actions:write

Saves an email that Pathbound holds: a draft that waits until you send it, or an email that goes out at send_at. The mailbox and the contact are checked now, with the same errors as Send an Email, so an email that could never be sent is refused when you create it.

The mailbox and the recipient’s address are fixed at this point. See What is checked when a scheduled email goes out.

Pass exactly one of draft: true and send_at.

send_at is an ISO 8601 date and time with an explicit offset or Z, for example 2026-10-20T09:00:00+02:00 or 2026-10-20T07:00:00Z. A time without an offset is refused, because the server cannot know your time zone. It can be at most 30 days ahead. A time up to 5 minutes in the past is accepted and treated as now. Anything earlier is refused.

curl -X POST https://api.pathbound.ai/v1/integrations/gmail/outbox \
  -H "Authorization: Bearer $PATHBOUND_API_KEY" \
  -H "Idempotency-Key: 2b6a9c4e-11d7-4f0b-8a3c-5e9d7f1c2a40" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "665f1c2ab3d4e5f601234567",
    "from": "[email protected]",
    "subject": "Next steps after the pilot",
    "body": "<p>Hi Ada,</p><p>Here is the plan we talked about.</p>",
    "send_at": "2026-10-20T09:00:00+02:00"
  }'

A scheduled email is answered with 202, a draft with 201 Created, and a repeated request with 200 OK and replayed: true. The body has the same shape each time.

{
  "status": "success",
  "action_id": "670bd1a2a1b2c3d4e5f60730",
  "email": {
    "outbox_id": "670bd1a2a1b2c3d4e5f60731",
    "status": "scheduled",
    "contact_id": "665f1c2ab3d4e5f601234567",
    "to": "[email protected]",
    "sender": "[email protected]",
    "subject": "Next steps after the pilot",
    "body_format": "html",
    "cc_count": 0,
    "bcc_count": 0,
    "include_signature": false,
    "send_at": "2026-10-20T07:00:00.000Z",
    "attempts": 0,
    "created_by": { "agent_id": "api_key:9f3c21ab" },
    "send_requested_by": { "agent_id": "api_key:9f3c21ab" },
    "action_id": "670bd1a2a1b2c3d4e5f60730",
    "created_at": "2026-10-13T14:05:38.120Z",
    "updated_at": "2026-10-13T14:05:38.120Z"
  }
}

A scheduled email goes out within about 30 seconds after send_at.

You can hold at most 200 open emails (drafts plus scheduled) at a time. There is no endpoint that edits a held email: cancel it and create a new one.

Every outbox endpoint returns the email in this shape. A field with no value is left out.

Statuses

Once an email is sent, failed or canceled, Pathbound removes its body and its cc and bcc addresses. The sent copy is in Gmail.

Deleting a contact deletes the emails held for that contact.

GET /v1/integrations/gmail/outbox

Required scope: actions:write

Returns your own outbox emails, newest first. You never see a teammate’s.

{
  "status": "success",
  "counts": { "total": 1, "draft": 1, "scheduled": 0, "sending": 0, "sent": 0, "failed": 0, "canceled": 0 },
  "has_more": false,
  "emails": [
    {
      "outbox_id": "670bd0e4a1b2c3d4e5f60719",
      "status": "draft",
      "contact_id": "665f1c2ab3d4e5f601234567",
      "to": "[email protected]",
      "sender": "[email protected]",
      "subject": "Next steps after the pilot",
      "body_format": "html",
      "cc_count": 1,
      "bcc_count": 0,
      "include_signature": false,
      "expires_at": "2026-11-12T14:02:11.482Z",
      "attempts": 0,
      "created_by": { "agent_id": "api_key:9f3c21ab" },
      "action_id": "670bd0e4a1b2c3d4e5f60718",
      "created_at": "2026-10-13T14:02:11.482Z",
      "updated_at": "2026-10-13T14:02:11.482Z",
      "body": "<p>Hi Ada,</p><p>Here is the plan we talked about.</p>",
      "cc": ["[email protected]"],
      "bcc": []
    }
  ]
}

subject and body are returned exactly as they will be sent.

counts gives how many emails the list holds in each status and in total. It counts every email that matches contact_id, whatever status, limit and after say. has_more is true when more emails follow the last one returned: pass that email’s outbox_id as after to read them.

POST /v1/integrations/gmail/outbox/:id/send

Required scope: actions:write

Sends a draft now, or schedules it when the body carries send_at. The email goes out from the mailbox the draft was written for, to the address it was written for. If that mailbox can no longer send, or the contact’s email has changed since, the request is refused and nothing is sent.

Sent now:

{
  "status": "success",
  "action_id": "670bd3c7a1b2c3d4e5f60742",
  "message_id": "19286f9b1e5a7c33",
  "thread_id": "19286f9b1e5a7c33",
  "sent_at": "2026-10-13T14:20:03.915Z",
  "sender": "[email protected]",
  "email": {
    "outbox_id": "670bd0e4a1b2c3d4e5f60719",
    "status": "sent"
  }
}

email is the full outbox email object, shortened here.

With send_at, the answer is 202 Accepted with status, action_id and email, and email.status is scheduled. You also get 202 for a send without send_at when the email was picked up for sending at the same moment: read email.status, and list the outbox to see how it ended.

A repeated request with the same Idempotency-Key returns 200 with replayed: true and the email as it is now, and sends nothing. Read email.status in that answer: an email whose send got no answer is replayed with status: "failed".

• Gmail refused it, or could not be reached. The draft is kept as a draft, with the reason in failure, and you can send it again. The answer is 502 GMAIL_SEND_FAILED with retry_after_seconds, or 422 THREAD_NOT_IN_MAILBOX.
• Gmail did not answer. The email becomes failed and the answer is 502 SEND_UNCONFIRMED. It is not sent again. See When Gmail does not answer.

These three answers carry email, the email as it is after the attempt.

DELETE /v1/integrations/gmail/outbox/:id

Required scope: actions:write

Discards a draft or cancels a scheduled email. Only an email in status draft or scheduled can be canceled.

{
  "status": "success",
  "email": {
    "outbox_id": "670bd1a2a1b2c3d4e5f60731",
    "status": "canceled"
  }
}

email is the full outbox email object, shortened here.

A scheduled email is sent long after the request that asked for it, so Pathbound checks again at that moment, in this order:

1. Whoever asked for the send may still send. The user is still a verified member of the workspace. For an API key: the key is still active, has not expired, and still holds actions:write. For an AI agent: its connection has not been disconnected.
2. The mailbox chosen when the email was created can still send. It is used or refused, never swapped for another mailbox.
3. The contact’s email is still the address the email was written for.

A check that fails ends the email as failed, with the reason in failure. Nothing is sent.

failure.code on an outbox email is one of these: