Skip to content

ConceptsOrganization access

Organization access

One call tells an agent whether it can go on with a setup. It returns the plan, whether mailboxes can be created, the trial, and how many mailboxes fit. It never returns payment methods, invoices or billing provider IDs.

Last updated

Request

GET/v1/organization/access

Any credential of the organization can call it, including an agent connection with the Set up permissions. It answers for the credential's own organization. For a connection that covers several organizations, send X-Shipmail-Organization. The MCP tool is shipmail_get_organization_access.

Response

{
  "object": "organization_access",
  "organization": { "id": "org_abc123", "name": "Acme", "default_timezone": "Europe/Paris" },
  "plan": "team",
  "has_access": true,
  "trial": { "active": true, "ends_at": "2026-10-19T09:00:00.000Z", "eligible": false },
  "mailboxes": { "limit": 3, "used": 1 },
  "newsletters_allowed": true
}
FieldTypeDescription
organizationobjectThe organization's id, name and default_timezone (an IANA zone, or null for Etc/UTC).
planstringfree, solo, pro, team or scale.
has_accessbooleanTrue when you can create a mailbox right now. It runs the same check as mailbox creation.
trial.activebooleanA trial is running.
trial.ends_atstring | nullWhen the trial ends, in ISO 8601 UTC.
trial.eligiblebooleanNo subscription yet and the owner never had a trial. Checkout still confirms it.
mailboxes.limitintegerMailboxes the organization can hold now. At most 3 in a trial.
mailboxes.usedintegerMailboxes it holds, counting creates in progress.
newsletters_allowedbooleanNewsletter sending is available. A trial sends newsletters within its trial limits.

Wait for the owner to pay

  • Send the owner the billing link from the agent setup steps. The owner reviews the price and pays in Shipmail.
  • Poll this endpoint every 10 seconds. Access appears once Shipmail has recorded the payment, a few seconds after checkout.
  • Then create mailboxes up to mailboxes.limit.

Examples

curl https://shipmail.to/api/v1/organization/access \
  -H "Authorization: Bearer <token>"