
Uploading a profile photo for one Google Workspace user takes a minute in the Admin console. Doing it for fifty, or for every outreach inbox you manage, is where admins look for a faster way. This guide covers a bulk profile picture update in Google Workspace: the options Google offers, step-by-step methods with the Directory API and the open-source GAM tool, preparing images, controlling whether users can change their own photos, verifying the result, and fixing common errors.
Forty Inboxes, Forty Grey Initials
๐ก TL;DR
For a bulk profile picture update in Google Workspace, use the Directory API's users.photos.update method or the GAM command-line tool with a CSV of email addresses and image files โ the Admin console only uploads one photo at a time, and Google Cloud Directory Sync doesn't sync photos. Prepare square, clearly lit images named by user, test on two or three accounts first, decide whether users may change their own photos, and check results in Gmail and the Directory.
An agency sets up forty new Google Workspace inboxes for a client's outbound program. Every one shows a grey circle with an initial. Recipients see that circle next to each email in Gmail, and the inboxes look less like real people. Uploading forty photos by hand, one user at a time in the Admin console, would take most of an afternoon.
Profile photos aren't just cosmetic for outreach. A real, professional photo helps a sender look like a person rather than a system โ which is why we include it in the setup standard in how to configure mailboxes for cold email.
By the end of this, you'll know exactly how to run a bulk profile picture update in Google Workspace in minutes, and how to keep photos consistent afterwards.
Your Options at a Glance
Method | Bulk? | Skill needed | Best for |
|---|---|---|---|
Admin console (Users โ user โ photo) | No โ one user at a time | None | A handful of users |
Users update their own photos | Indirectly | None | Staff mailboxes where people manage their profiles |
GAM (open-source command-line tool) | Yes, from a CSV or file pattern | Basic command line | Most admins doing a one-off or repeat bulk update |
Directory API (users.photos.update) | Yes, via your own script | Developer | Automated pipelines and platforms |
Google Cloud Directory Sync (GCDS) | No โ photos aren't synced | โ | Other profile fields, not photos |
The GCDS row surprises people. Google's own profile update guide lists profile photo as available through the Admin console and the Directory API's Users.photos, but not through GCDS. So if your directory sync handles everything else, photos still need a separate step.
Step 1: Prepare the Images
Good preparation prevents most failures during a bulk profile picture update in Google Workspace.
Square crop, with the face centered โ photos display in a circle.
Consistent style across the team: similar background, lighting, and framing.
Common formats such as JPEG or PNG, at a reasonable resolution; check the API reference for accepted formats and size limits before a big batch.
Name files predictably โ for example, the user's primary email address plus .jpg โ so scripts can match files to users.
Use real people's photos with their consent. Don't use stock photos or images of people who don't send from that mailbox.
Keep the originals in one shared folder with the same names you'll use in the CSV. When a new person joins or a mailbox changes owner, you can rerun a bulk profile picture update in Google Workspace for just that person by adding one row, instead of hunting for the right file.
That last point matters for outreach in particular. A stock photo on a real sender's inbox misleads recipients, and an honest sender identity is part of trustworthy outreach.
Step 2: Bulk Update With GAM
GAM is a widely used, open-source command-line tool for Google Workspace admins. Once it's installed and authorized with the Directory API user scope, a bulk update takes one command.
Option A: a CSV file
Create a CSV with two columns, primaryEmail and photofile, listing each user and the path to their image. Then run a command along these lines:
Option B: a file-naming pattern
If every photo is named after the user (for example, jordan@getacme.com.jpg) and stored in one folder, GAM can substitute the user's address into the path:
GAM prints a result line for each user, so save the output to a file when you run a large batch.
Use a narrower target than "all users" โ a group or organizational unit โ when you only want to update outreach inboxes. Check GAM's current documentation for exact syntax in your version; commands occasionally change between releases.
๐ก Test on three accounts first
Run the command against a small CSV of two or three users, check the results in Gmail, then run the full batch. It's much easier to fix a cropping problem on three photos than on three hundred.
Step 3 (Alternative): Use the Directory API
For automated setups โ for example, a platform that creates mailboxes for customers โ call the Directory API directly.
Enable the Admin SDK API in a Google Cloud project.
Authorize a service account with domain-wide delegation for the https://www.googleapis.com/auth/admin.directory.user scope, impersonating an admin.
Read each image and encode it as the API expects (web-safe base64 in the photo data field).
Call users.photos.update โ a PUT to /admin/directory/v1/users/{userKey}/photos/thumbnail โ with the photo data and MIME type.
Retry with backoff on rate-limit errors, and log each user's result.
Google's users.photos.update reference documents the request. If you're building a full provisioning flow, photos fit naturally into the steps in automating Google Workspace mailbox provisioning.
Step 4: Decide Whether Users Can Change Their Own Photos
Google Workspace lets admins allow or prevent users from editing some profile settings, including their photo. Choose deliberately.
Mailbox type | Suggested setting | Why |
|---|---|---|
Staff mailboxes | Allow users to change photos | People keep their own profiles current |
Outreach inboxes managed centrally | Prevent changes | Keeps photos consistent with your standard |
Shared or role mailboxes | Prevent changes; use a logo or team photo only if appropriate | Avoids random personal photos on shared addresses |
Here's the advice we'd push back on: "Just let everyone upload whatever they like." For staff, that's usually fine. For a pool of outreach inboxes, it leads to mismatched, sometimes unprofessional photos within weeks. Use organizational units to apply different settings to different groups.
Verify and Troubleshoot
After a bulk profile picture update in Google Workspace, check the results where recipients will see them.
Open Gmail as a recipient and look at the sender's avatar on a test message.
Check the user's profile card in the Google Workspace Directory.
Review GAM's output or your script's log for any failures.
Allow some time โ new photos can take a while to appear everywhere.
Problem | Likely cause | Fix |
|---|---|---|
Photo didn't change | Wrong file path or user address in the CSV | Check the CSV and rerun for that user |
Permission error | Tool not authorized for the user scope | Re-authorize GAM or the service account with the Directory API user scope |
Photo looks cropped badly | Image not square or face off-center | Re-crop and upload again |
Recipients still see an initial | Change not yet visible, or a different account sent the email | Wait and recheck; confirm the sending address |
Users replaced the photos | User photo changes allowed | Restrict changes for that organizational unit |
Photos are one part of a trustworthy sender identity, along with real names, clean signatures, and authenticated domains โ see cold email infrastructure setup. Litemail Google Workspace inboxes come with full admin access, so you can run photo updates and other admin tasks yourself.
Inboxes you can fully administer โ Litemail Google Workspace inboxes come with full Google Admin console access for photos, signatures, and security, plus SPF/DKIM/DMARC pre-configured, dedicated US and EU IPs, and pre-warmed options. See Pre-Warmed Inbox Plans โ About Litemail โ Litemail provides pre-warmed Google Workspace and Microsoft 365 inboxes for cold email outreach, with automated DNS, dedicated US and EU IPs, and full admin access. Pre-warmed plans start at $39/month for 5 inboxes; add-on inboxes go as low as $4.99/inbox on the Scale plan. View pre-warmed inbox plans โ
Related reading: Configure Mailboxes for Cold Email ยท Automate Google Workspace Mailbox Provisioning ยท Automating Google Workspace Inbox Setup ยท Google Workspace Inboxes
Key Takeaways
For a bulk profile picture update in Google Workspace, use GAM with a CSV or file pattern, or the Directory API's users.photos.update.
The Admin console uploads one photo at a time, and Google Cloud Directory Sync doesn't sync photos.
Prepare square, consistent, properly named images, and use real people's photos with consent.
Test on two or three accounts before running the full batch.
Decide by organizational unit whether users may change their own photos.
Verify in Gmail and the Directory, and log failures for a quick rerun.
Frequently Asked Questions
How do I do a bulk profile picture update in Google Workspace?
Use GAM with a CSV of email addresses and image paths, or a script calling the Directory API's users.photos.update method. The Admin console only handles one user at a time.
Can Google Cloud Directory Sync update profile photos?
No. Google's documentation lists profile photos as available through the Admin console and Directory API, but not through GCDS.
What permissions does a bulk photo update need?
The Directory API user scope, https://www.googleapis.com/auth/admin.directory.user, granted to GAM or a service account acting as an admin.
Can I stop users from changing their profile photos?
Yes. Admins can control whether users may edit their profile photo, and apply different settings to different organizational units.
How long do new profile photos take to appear?
Often quickly, but it can take some time for changes to show everywhere. Recheck later before troubleshooting.
Should outreach inboxes have profile photos?
Yes โ real, professional photos of the actual sender help the inbox look like a person. Don't use stock images.
Can I update photos on Litemail inboxes?
Yes. Litemail Google Workspace inboxes include full admin access, so you can run bulk photo updates with GAM or the Directory API.
Google Workspace Inboxes With Full Admin Control
Litemail Google Workspace inboxes come with full admin access, SPF/DKIM/DMARC configured, dedicated US and EU IPs, sending history on pre-warmed plans, and free domain replacement.
Plans from $39/month ยท Google Workspace and Microsoft 365 ยท Setup in about 5 minutes
Buy Pre-Warmed Email Inboxes & Domains | Litemail โ Pre-warmed Google Workspace and Microsoft 365 inboxes with automated DNS, US and EU IPs, and setup in about 5 minutes. Fresh inboxes from $2.50/inbox; pre-warmed from $4.99/inbox at scale. View plans and pricing โ
Related reading: Google Workspace Pre-Warmed Accounts ยท Cold Email Inboxes for Agencies ยท Manage Outbound Mailboxes Across Business Units ยท Cold Email Deliverability Guide ยท Litemail Home ยท Plans and Pricing


