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
      • business_unit object
        Hide business_unit attributes Show business_unit 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
      • last_interaction_at object
        Hide last_interaction_at attributes Show last_interaction_at attributes object
        • example string
        • description string
        • collection boolean
      • referral_code object
        Hide referral_code attributes Show referral_code attributes object
        • example string
        • description string
        • collection boolean
      • permissions object
        Hide permissions attributes Show permissions attributes object
        • example object
          Hide example attributes Show example attributes object
          • firm:read array[string]
          • network:read array[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, disconnected and deleting

    • 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) 
{
  "uuid": "4fc00e84-1275-44ea-988e-64a934202f0f",
  "created_at": "2026-04-29T16:54:30+01:00",
  "updated_at": "2026-04-29T16:54:30+01:00",
  "created_by": {
    "uuid": {
      "example": "3d7c1593-9a8f-4a8f-a290-0c31880bb429",
      "description": "The UUID of the resource.",
      "collection": false
    },
    "created_at": {
      "example": "2026-04-29T16:54:30+01:00",
      "description": "The timestamp of when the resource was created.",
      "collection": false
    },
    "updated_at": {
      "example": "2026-04-29T16:54:30+01:00",
      "description": "The timestamp of when the resource was updated.",
      "collection": false
    },
    "type": {
      "example": "client",
      "description": "Account type",
      "collection": false
    },
    "role": {
      "example": "client",
      "description": "Account role",
      "collection": false
    },
    "first_name": {
      "example": "Gareth",
      "description": "First name",
      "collection": false
    },
    "last_name": {
      "example": "Thompson",
      "description": "Last name",
      "collection": false
    },
    "name": {
      "example": "Gareth Thompson",
      "description": "Name",
      "collection": false
    },
    "email": {
      "example": "gareth@codepotato.co.uk",
      "description": "(Deprecated - Please use primary_email instead). The email of the account.",
      "collection": false
    },
    "photo_url": {
      "example": "https://eu.ui-avatars.com/api/?name=gareth+thompson",
      "description": "URL for initial avatar image",
      "collection": false
    },
    "firm": {
      "example": "App\\Http\\Resources\\FirmResource",
      "description": "Firm",
      "collection": false
    },
    "primary_phone_number": {
      "example": "App\\Http\\Resources\\ContactDetailResource",
      "description": "Primary phone number",
      "collection": false
    },
    "primary_email": {
      "example": "App\\Http\\Resources\\ContactDetailResource",
      "description": "Primary email",
      "collection": false
    },
    "current_time_entry": {
      "example": "App\\Http\\Resources\\TimeEntryResource",
      "description": "Current time entry",
      "collection": false
    },
    "assigned_adviser": {
      "example": "App\\Http\\Resources\\AccountResource",
      "description": "Assigned adviser",
      "collection": false
    },
    "assigned_administrator": {
      "example": "App\\Http\\Resources\\AccountResource",
      "description": "Assigned administrator",
      "collection": false
    },
    "assigned_paraplanner": {
      "example": "App\\Http\\Resources\\AccountResource",
      "description": "Assigned paraplanner",
      "collection": false
    },
    "introduced_by": {
      "example": "App\\Http\\Resources\\AccountResource",
      "description": "Introduced by",
      "collection": false
    },
    "business_unit": {
      "example": "App\\Http\\Resources\\BusinessUnitResource",
      "description": "The business unit this account belongs to",
      "collection": false
    },
    "groups": {
      "example": "App\\Http\\Resources\\GroupResource",
      "description": "Groups",
      "collection": true
    },
    "tags": {
      "example": "App\\Http\\Resources\\TagResource",
      "description": "Tags",
      "collection": true
    },
    "owners": {
      "example": "App\\Http\\Resources\\AccountResource",
      "description": "Accounts that own this account",
      "collection": true
    },
    "first_contact_date": {
      "example": "2026-04-29T16:54:30+01:00",
      "description": "First contact date",
      "collection": false
    },
    "next_review_date": {
      "example": "2026-04-29T16:54:30+01:00",
      "description": "Next review date",
      "collection": false
    },
    "previous_review_date": {
      "example": "2026-04-29T16:54:30+01:00",
      "description": "Previous review date",
      "collection": false
    },
    "anniversary_review_date": {
      "example": "2026-04-29T16:54:30+01:00",
      "description": "Anniversary review date",
      "collection": false
    },
    "with_login": {
      "example": true,
      "description": "Denotes whether the account has a login to Plannr",
      "collection": false
    },
    "has_joint_account": {
      "example": true,
      "description": "Denotes whether this account belongs to a joint account too",
      "collection": false
    },
    "can_be_deleted": {
      "example": "false",
      "description": "Denotes if the account can be deleted",
      "collection": false
    },
    "joint_account_circle": {
      "example": "App\\Http\\Resources\\CircleResource",
      "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.",
      "collection": false
    },
    "circles": {
      "example": "App\\Http\\Resources\\CircleResource",
      "description": "The circles the account belongs to",
      "collection": true
    },
    "ownership_percentage": {
      "example": 100,
      "description": "Percentage ownership of the plan (This field is only present if viewing the account record via a plans relationship eg Plan -> Accounts)",
      "collection": false
    },
    "inactive_at": {
      "example": "2026-04-29",
      "description": "Inactive from date",
      "collection": false
    },
    "last_interaction_at": {
      "example": "2026-04-29 16:54:30",
      "description": "Last interaction date",
      "collection": false
    },
    "referral_code": {
      "example": "ABC12345",
      "description": "Unique referral code for the employee account (employees only)",
      "collection": false
    },
    "permissions": {
      "example": {
        "firm:read": [
          "firm"
        ],
        "network:read": [
          "network:uuid"
        ]
      },
      "description": "Permission map where keys are permission names and values are target arrays",
      "collection": false
    },
    "custom_fields": {
      "example": "App\\Http\\Resources\\CustomFieldValueResource",
      "description": "Any custom fields on the model.",
      "collection": true
    },
    "external_references": {
      "example": "App\\Http\\Resources\\ExternalReferenceResource",
      "description": "The external references that have been added to the client.",
      "collection": true
    }
  },
  "type": "imap",
  "email": "test@example.org",
  "name": "Test Mailbox",
  "state": "connected",
  "enabled": true,
  "message_count": 1
}