PUT /api/v1/mailboxes/{uuid}
Personal access token & O auth2

If the mailbox is disabled, we will disable the IMAP connection, which will stop webhooks being received for new messages.

Headers

  • X-PLANNR-ACCOUNT-UUID string

Path parameters

  • uuid string Required

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • uuid string

      The UUID of the resource.

    • created_at string

      The timestamp of when the resource was created.

    • updated_at string

      The timestamp of when the resource was updated.

    • created_by object

      The account that created this mailbox.

      Hide created_by attributes Show created_by attributes object
      • uuid object
        Hide uuid attributes Show uuid attributes object
        • example string
        • description string
        • collection boolean
      • created_at object
        Hide created_at attributes Show created_at attributes object
        • example string
        • description string
        • collection boolean
      • updated_at object
        Hide updated_at attributes Show updated_at attributes object
        • example string
        • description string
        • collection boolean
      • type object
        Hide type attributes Show type attributes object
        • example string
        • description string
        • collection boolean
      • role object
        Hide role attributes Show role attributes object
        • example string
        • description string
        • collection boolean
      • first_name object
        Hide first_name attributes Show first_name attributes object
        • example string
        • description string
        • collection boolean
      • last_name object
        Hide last_name attributes Show last_name attributes object
        • example string
        • description string
        • collection boolean
      • name object
        Hide name attributes Show name attributes object
        • example string
        • description string
        • collection boolean
      • email object
        Hide email attributes Show email attributes object
        • example string
        • description string
        • collection boolean
      • photo_url object
        Hide photo_url attributes Show photo_url attributes object
        • example string
        • description string
        • collection boolean
      • firm object
        Hide firm attributes Show firm attributes object
        • example string
        • description string
        • collection boolean
      • primary_phone_number object
        Hide primary_phone_number attributes Show primary_phone_number attributes object
        • example string
        • description string
        • collection boolean
      • primary_email object
        Hide primary_email attributes Show primary_email attributes object
        • example string
        • description string
        • collection boolean
      • current_time_entry object
        Hide current_time_entry attributes Show current_time_entry attributes object
        • example string
        • description string
        • collection boolean
      • assigned_adviser object
        Hide assigned_adviser attributes Show assigned_adviser attributes object
        • example string
        • description string
        • collection boolean
      • assigned_administrator object
        Hide assigned_administrator attributes Show assigned_administrator attributes object
        • example string
        • description string
        • collection boolean
      • assigned_paraplanner object
        Hide assigned_paraplanner attributes Show assigned_paraplanner attributes object
        • example string
        • description string
        • collection boolean
      • introduced_by object
        Hide introduced_by attributes Show introduced_by attributes object
        • example string
        • description string
        • collection boolean
      • groups object
        Hide groups attributes Show groups attributes object
        • example string
        • description string
        • collection boolean
      • tags object
        Hide tags attributes Show tags attributes object
        • example string
        • description string
        • collection boolean
      • owners object
        Hide owners attributes Show owners attributes object
        • example string
        • description string
        • collection boolean
      • first_contact_date object
        Hide first_contact_date attributes Show first_contact_date attributes object
        • example string
        • description string
        • collection boolean
      • next_review_date object
        Hide next_review_date attributes Show next_review_date attributes object
        • example string
        • description string
        • collection boolean
      • previous_review_date object
        Hide previous_review_date attributes Show previous_review_date attributes object
        • example string
        • description string
        • collection boolean
      • anniversary_review_date object
        Hide anniversary_review_date attributes Show anniversary_review_date attributes object
        • example string
        • description string
        • collection boolean
      • with_login object
        Hide with_login attributes Show with_login attributes object
        • example boolean
        • description string
        • collection boolean
      • has_joint_account object
        Hide has_joint_account attributes Show has_joint_account attributes object
        • example boolean
        • description string
        • collection boolean
      • can_be_deleted object
        Hide can_be_deleted attributes Show can_be_deleted attributes object
        • example string
        • description string
        • collection boolean
      • joint_account_circle object
        Hide joint_account_circle attributes Show joint_account_circle attributes object
        • example string
        • description string
        • collection boolean
      • circles object
        Hide circles attributes Show circles attributes object
        • example string
        • description string
        • collection boolean
      • ownership_percentage object
        Hide ownership_percentage attributes Show ownership_percentage attributes object
        • example integer
        • description string
        • collection boolean
      • inactive_at object
        Hide inactive_at attributes Show inactive_at attributes object
        • example string
        • description string
        • collection boolean
      • custom_fields object
        Hide custom_fields attributes Show custom_fields attributes object
        • example string
        • description string
        • collection boolean
      • external_references object
        Hide external_references attributes Show external_references attributes object
        • example string
        • description string
        • collection boolean
    • type string

      The type of mailbox this is. Possible values are: imap, gmail and outlook

    • email string

      The email address of the mailbox.

    • name string

      The name of the mailbox.

    • state string

      The status of the mailbox. Possible values are: init, syncing, connecting, connected, authenticationError, connectError, unset and disconnected

    • enabled boolean

      Whether the mailbox is enabled or not.

    • message_count integer

      The number of messages synced by this mailbox.
PUT /api/v1/mailboxes/{uuid} 
curl \
 --request PUT 'https://api.plannrcrm.com/api/v1/mailboxes/6ff8f7f6-1eb3-3525-be4a-3932c805afed' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "X-PLANNR-ACCOUNT-UUID: {YOUR_PLANNR_ACCOUNT_UUID}"
Response examples (200) 
{
  "name": "Test Mailbox",
  "type": "imap",
  "uuid": "ee603b64-ac1b-49a2-bb3b-801d4e80eccf",
  "email": "test@example.org",
  "state": "connected",
  "enabled": true,
  "created_at": "2025-12-04T22:09:15+00:00",
  "created_by": {
    "firm": {
      "example": "App\\Http\\Resources\\FirmResource",
      "collection": false,
      "description": "Firm"
    },
    "name": {
      "example": "Gareth Thompson",
      "collection": false,
      "description": "Name"
    },
    "role": {
      "example": "client",
      "collection": false,
      "description": "Account role"
    },
    "tags": {
      "example": "App\\Http\\Resources\\TagResource",
      "collection": true,
      "description": "Tags"
    },
    "type": {
      "example": "client",
      "collection": false,
      "description": "Account type"
    },
    "uuid": {
      "example": "773936c1-2161-4df8-afe3-af1f8ecab8bf",
      "collection": false,
      "description": "The UUID of the resource."
    },
    "email": {
      "example": "gareth@codepotato.co.uk",
      "collection": false,
      "description": "(Deprecated - Please use primary_email instead). The email of the account."
    },
    "groups": {
      "example": "App\\Http\\Resources\\GroupResource",
      "collection": true,
      "description": "Groups"
    },
    "owners": {
      "example": "App\\Http\\Resources\\AccountResource",
      "collection": true,
      "description": "Accounts that own this account"
    },
    "circles": {
      "example": "App\\Http\\Resources\\CircleResource",
      "collection": true,
      "description": "The circles the account belongs to"
    },
    "last_name": {
      "example": "Thompson",
      "collection": false,
      "description": "Last name"
    },
    "photo_url": {
      "example": "https://eu.ui-avatars.com/api/?name=gareth+thompson",
      "collection": false,
      "description": "URL for initial avatar image"
    },
    "created_at": {
      "example": "2025-12-04T22:09:15+00:00",
      "collection": false,
      "description": "The timestamp of when the resource was created."
    },
    "first_name": {
      "example": "Gareth",
      "collection": false,
      "description": "First name"
    },
    "updated_at": {
      "example": "2025-12-04T22:09:15+00:00",
      "collection": false,
      "description": "The timestamp of when the resource was updated."
    },
    "with_login": {
      "example": true,
      "collection": false,
      "description": "Denotes whether the account has a login to Plannr"
    },
    "inactive_at": {
      "example": "2025-12-04",
      "collection": false,
      "description": "Inactive from date"
    },
    "custom_fields": {
      "example": "App\\Http\\Resources\\CustomFieldValueResource",
      "collection": true,
      "description": "Any custom fields on the model."
    },
    "introduced_by": {
      "example": "App\\Http\\Resources\\AccountResource",
      "collection": false,
      "description": "Introduced by"
    },
    "primary_email": {
      "example": "App\\Http\\Resources\\ContactDetailResource",
      "collection": false,
      "description": "Primary email"
    },
    "can_be_deleted": {
      "example": "false",
      "collection": false,
      "description": "Denotes if the account can be deleted"
    },
    "assigned_adviser": {
      "example": "App\\Http\\Resources\\AccountResource",
      "collection": false,
      "description": "Assigned adviser"
    },
    "next_review_date": {
      "example": "2025-12-04T22:09:15+00:00",
      "collection": false,
      "description": "Next review date"
    },
    "has_joint_account": {
      "example": true,
      "collection": false,
      "description": "Denotes whether this account belongs to a joint account too"
    },
    "current_time_entry": {
      "example": "App\\Http\\Resources\\TimeEntryResource",
      "collection": false,
      "description": "Current time entry"
    },
    "first_contact_date": {
      "example": "2025-12-04T22:09:15+00:00",
      "collection": false,
      "description": "First contact date"
    },
    "external_references": {
      "example": "App\\Http\\Resources\\ExternalReferenceResource",
      "collection": true,
      "description": "The external references that have been added to the client."
    },
    "assigned_paraplanner": {
      "example": "App\\Http\\Resources\\AccountResource",
      "collection": false,
      "description": "Assigned paraplanner"
    },
    "joint_account_circle": {
      "example": "App\\Http\\Resources\\CircleResource",
      "collection": false,
      "description": "This field is only present when viewing a joint account directly. This will contain the circle that we automatically created when we released circles."
    },
    "ownership_percentage": {
      "example": 100,
      "collection": false,
      "description": "Percentage ownership of the plan (This field is only present if viewing the account record via a plans relationship eg Plan -> Accounts)"
    },
    "previous_review_date": {
      "example": "2025-12-04T22:09:15+00:00",
      "collection": false,
      "description": "Previous review date"
    },
    "primary_phone_number": {
      "example": "App\\Http\\Resources\\ContactDetailResource",
      "collection": false,
      "description": "Primary phone number"
    },
    "assigned_administrator": {
      "example": "App\\Http\\Resources\\AccountResource",
      "collection": false,
      "description": "Assigned administrator"
    },
    "anniversary_review_date": {
      "example": "2025-12-04T22:09:15+00:00",
      "collection": false,
      "description": "Anniversary review date"
    }
  },
  "updated_at": "2025-12-04T22:09:15+00:00",
  "message_count": 1
}