Mailgun

Run a valid mailgun.list_emails call through the same SDK surface used by every toolkit.

Minimal tool call

import { Eyeball } from "@eyeball/sdk";

const eyeball = new Eyeball({
  apiKey: process.env.EYEBALL_API_KEY!,
  baseUrl: process.env.EYEBALL_EXECUTOR_URL!,
});

const output = await eyeball.tools.run(
  "mailgun.list_emails",
  {
  "unreadOnly": false,
  "pageSize": 50
},
  { userId: "demo_user" },
);
console.log(output);

The model receives canonical output. Your application retains the execution envelope through tools.execute or the execution APIs when it needs IDs, status, versions, and latency.

Supported canonical tools

Tool	Purpose	Execution	Effect	Version
`mailgun.list_emails`	List email messages from a mailbox, folder, or label with portable filters and pagination. Use this to browse messages; use search_emails when a provider query expression is the primary selector.	sync or async	read	`1.0.0`
`mailgun.send_email`	Send a new email from the connected email account. Use this for a new conversation, not a reply to an existing message or thread. This sends content to external recipients; verify recipients, subject, and body first.	sync or async	mutation	`1.1.0`

Only the rows above are implemented. A capability tool omitted by this manifest returns not_supported; eyeball never synthesizes provider parity.

Supported canonical triggers

This manifest does not implement a canonical trigger.

Input and output schemas

mailgun.list_emails

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:eyeball:email:list_emails:1.0.0:mailgun",
  "type": "object",
  "description": "Mailbox location, filters, and pagination for listing email messages.",
  "additionalProperties": false,
  "properties": {
    "mailboxId": {
      "type": "string",
      "description": "Mailbox identifier; omit to use the connected account's default mailbox.",
      "minLength": 1
    },
    "folderId": {
      "type": "string",
      "description": "Folder identifier used to restrict the mailbox listing.",
      "minLength": 1
    },
    "labelIds": {
      "type": "array",
      "description": "Labels or categories every returned email should have.",
      "items": {
        "type": "string",
        "description": "Provider label or category identifier.",
        "minLength": 1
      }
    },
    "from": {
      "type": "string",
      "format": "email",
      "description": "Return only emails from this sender address."
    },
    "to": {
      "type": "string",
      "format": "email",
      "description": "Return only emails addressed to this recipient."
    },
    "subject": {
      "type": "string",
      "description": "Case-insensitive subject text to match.",
      "minLength": 1
    },
    "receivedAfter": {
      "type": "string",
      "format": "date-time",
      "description": "Return emails received at or after this RFC 3339 timestamp."
    },
    "receivedBefore": {
      "type": "string",
      "format": "date-time",
      "description": "Return emails received before this RFC 3339 timestamp."
    },
    "unreadOnly": {
      "type": "boolean",
      "description": "When true, return only unread emails.",
      "default": false
    },
    "hasAttachments": {
      "type": "boolean",
      "description": "When supplied, filter by whether an email has attachments."
    },
    "pageSize": {
      "type": "integer",
      "description": "Maximum number of emails to return in one page.",
      "minimum": 1,
      "maximum": 100,
      "default": 50
    },
    "pageToken": {
      "type": "string",
      "description": "Opaque continuation token from a previous email page.",
      "minLength": 1
    },
    "x_provider": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "mailgun": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "domain"
          ],
          "properties": {
            "domain": {
              "type": "string",
              "description": "Mailgun sending domain used in the API route.",
              "minLength": 1
            }
          }
        }
      }
    }
  }
}

Output schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:eyeball:email:list_emails:output:1.0.0:mailgun",
  "type": "object",
  "description": "One page of email summaries and an optional continuation token.",
  "additionalProperties": false,
  "required": [
    "emails"
  ],
  "properties": {
    "emails": {
      "type": "array",
      "description": "Email summaries in provider-defined mailbox order.",
      "items": {
        "type": "object",
        "description": "Compact mailbox metadata for one email message.",
        "additionalProperties": false,
        "required": [
          "messageId",
          "from",
          "to",
          "subject",
          "receivedAt",
          "unread",
          "hasAttachments"
        ],
        "properties": {
          "messageId": {
            "type": "string",
            "description": "Provider identifier of the email message.",
            "minLength": 1
          },
          "threadId": {
            "type": "string",
            "description": "Provider identifier of the containing conversation thread.",
            "minLength": 1
          },
          "from": {
            "type": "string",
            "format": "email",
            "description": "Sender email address."
          },
          "to": {
            "type": "array",
            "description": "Primary recipient email addresses.",
            "items": {
              "type": "string",
              "format": "email",
              "description": "A syntactically valid email address."
            }
          },
          "subject": {
            "type": "string",
            "description": "Email subject exactly as stored by the provider."
          },
          "snippet": {
            "type": "string",
            "description": "Short provider-generated preview of the email body."
          },
          "receivedAt": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp when the mailbox received the email."
          },
          "unread": {
            "type": "boolean",
            "description": "Whether the email is currently marked unread."
          },
          "hasAttachments": {
            "type": "boolean",
            "description": "Whether the email includes at least one attachment."
          },
          "labelIds": {
            "type": "array",
            "description": "Provider label, category, or folder identifiers on the email.",
            "items": {
              "type": "string",
              "description": "Provider identifier of an applied label, category, or folder.",
              "minLength": 1
            }
          }
        }
      }
    },
    "nextPageToken": {
      "type": "string",
      "description": "Opaque token to request the next page of emails; absent when the result is complete.",
      "minLength": 1
    }
  }
}

mailgun.send_email

Input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:eyeball:email:send_email:1.1.0:mailgun",
  "type": "object",
  "description": "Recipients, content, and staged attachments for a new email.",
  "additionalProperties": false,
  "required": [
    "to",
    "subject",
    "body"
  ],
  "properties": {
    "to": {
      "type": "array",
      "description": "Primary recipient email addresses.",
      "items": {
        "type": "string",
        "format": "email",
        "description": "A syntactically valid email address."
      },
      "minItems": 1
    },
    "cc": {
      "type": "array",
      "description": "Carbon-copy recipient email addresses.",
      "items": {
        "type": "string",
        "format": "email",
        "description": "A syntactically valid email address."
      }
    },
    "bcc": {
      "type": "array",
      "description": "Blind-carbon-copy recipient email addresses.",
      "items": {
        "type": "string",
        "format": "email",
        "description": "A syntactically valid email address."
      }
    },
    "subject": {
      "type": "string",
      "description": "Subject line shown to recipients.",
      "minLength": 1,
      "maxLength": 998
    },
    "body": {
      "type": "string",
      "description": "Complete body in the format selected by bodyFormat.",
      "minLength": 1
    },
    "bodyFormat": {
      "type": "string",
      "description": "Serialization format of the body content.",
      "enum": [
        "text",
        "html"
      ],
      "default": "text"
    },
    "replyTo": {
      "type": "string",
      "format": "email",
      "description": "Address recipients should use when replying instead of the sender."
    },
    "attachments": {
      "type": "array",
      "description": "Previously staged Eyeball files to attach.",
      "maxItems": 25,
      "items": {
        "description": "A staged file reference that the provider can attach.",
        "anyOf": [
          {
            "type": "object",
            "description": "Preferred staged-file reference shape.",
            "additionalProperties": false,
            "required": [
              "fileId"
            ],
            "properties": {
              "fileId": {
                "type": "string",
                "description": "Eyeball file_* identifier returned by POST /v1/files.",
                "pattern": "^file_[A-Za-z0-9][A-Za-z0-9_-]{0,127}$"
              },
              "name": {
                "type": "string",
                "description": "Optional recipient-visible name overriding staged metadata.",
                "minLength": 1
              },
              "mimeType": {
                "type": "string",
                "description": "Optional MIME type overriding staged metadata for delivery.",
                "minLength": 1
              }
            }
          },
          {
            "type": "object",
            "description": "Deprecated 1.0 staged-file reference retained for compatibility.",
            "additionalProperties": false,
            "required": [
              "fileId",
              "fileName"
            ],
            "properties": {
              "fileId": {
                "type": "string",
                "description": "Eyeball identifier of the previously staged file.",
                "minLength": 1
              },
              "fileName": {
                "type": "string",
                "description": "Deprecated recipient-visible name; use name in new calls.",
                "minLength": 1
              },
              "contentType": {
                "type": "string",
                "description": "Deprecated MIME type; use mimeType in new calls.",
                "minLength": 1
              }
            }
          }
        ]
      }
    },
    "x_provider": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "mailgun": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "domain",
            "from"
          ],
          "properties": {
            "domain": {
              "type": "string",
              "description": "Mailgun sending domain used in the API route.",
              "minLength": 1
            },
            "from": {
              "type": "string",
              "description": "Verified Mailgun sender, optionally with a display name.",
              "minLength": 1
            }
          }
        }
      }
    }
  }
}

Output schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:eyeball:email:send_email:output:1.1.0:mailgun",
  "type": "object",
  "description": "Identifiers and accepted recipients for the newly sent email.",
  "additionalProperties": false,
  "required": [
    "messageId",
    "acceptedRecipients"
  ],
  "properties": {
    "messageId": {
      "type": "string",
      "description": "Provider identifier of the created email message.",
      "minLength": 1
    },
    "threadId": {
      "type": "string",
      "description": "Provider identifier of the conversation thread when available.",
      "minLength": 1
    },
    "acceptedRecipients": {
      "type": "array",
      "description": "Recipient addresses accepted by the provider for delivery.",
      "items": {
        "type": "string",
        "format": "email",
        "description": "A syntactically valid email address."
      }
    }
  }
}

Authentication

Property	Value
Auth class	`api_key`
Required scopes	None
Optional scopes	None
Credential fields	`apiKey`

Credentials are resolved inside the executor by CredentialProvider. They never belong in tool input, x_provider, model context, logs, or execution output.

Provider-specific extensions

`mailgun.send_email` input

input.x_provider.mailgun accepts:

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "domain",
    "from"
  ],
  "properties": {
    "domain": {
      "type": "string",
      "description": "Mailgun sending domain used in the API route.",
      "minLength": 1
    },
    "from": {
      "type": "string",
      "description": "Verified Mailgun sender, optionally with a display name.",
      "minLength": 1
    }
  }
}

`mailgun.list_emails` input

input.x_provider.mailgun accepts:

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "domain"
  ],
  "properties": {
    "domain": {
      "type": "string",
      "description": "Mailgun sending domain used in the API route.",
      "minLength": 1
    }
  }
}

Provider differences may appear only under x_provider.mailgun and only when the schema above declares them.

Sync and async behavior

All tools are synchronous by nature, but callers may choose mode: "async" to queue them.

Mutations require a stable Idempotency-Key. The TypeScript SDK accepts it as idempotencyKey; it is never part of the JSON request body.

REST example

curl "$EYEBALL_EXECUTOR_URL/v1/execute" \
  -H "Authorization: Bearer $EYEBALL_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"tool":"mailgun.list_emails","userId":"demo_user","input":{"unreadOnly":false,"pageSize":50},"mode":"sync"}'

Point EYEBALL_EXECUTOR_URL at a mock-configured executor to run through the real catalog, validation, credential seam, adapter, normalized errors, and execution records with no Mailgun account. Mock selection changes the executor endpoint and trusted provider base-URL configuration, never the execute request.

Limitations

This page describes the manifest's explicit P1 subset, not every operation offered by the provider.
Provider account policy, consent UI, quota details, and current wire compatibility still require a real-provider certification pass.
Fields outside the canonical schemas and declared x_provider extensions are rejected.

Versions

Contract	Version
Runtime catalog	`1.1`
Manifest catalog	`1.0`
Manifest schema	`1.0`
Source	`activepieces-bridge`
Tier	`P1`
Capabilities	`email`

Use Testing with mocks to exercise this toolkit before connecting a live provider account.