Importing Contacts

Once you’ve generated recursers.vcf, you can import it into any contact manager that supports the vCard format. This guide covers the most common platforms.

Overview

The generated VCF file:

Contains all Recursers in a single file
Includes embedded photos (base64-encoded)
Follows the vCard 3.0 specification
Uses unique IDs (recurser-{id}) to prevent duplicates
Typically 40-50 MB in size due to photos

Before importing, consider backing up your existing contacts. While the unique IDs should prevent duplicates, it’s always safer to have a backup.

Import Instructions by Platform

iOS Contacts
Google Contacts
Outlook
macOS Contacts
Other Apps

Method 1: AirDrop (Recommended)

Transfer the file

AirDrop the recursers.vcf file from your computer to your iPhone or iPad.

Open the file

Tap the file when it appears in AirDrop. This will open it in the Contacts app.

Import all contacts

iOS will ask if you want to add all contacts. Tap “Add All [number] Contacts”.

Wait for completion

The import may take 1-2 minutes for thousands of contacts. Don’t close the Contacts app during this time.

Method 2: Email

Email yourself the file

Send recursers.vcf to an email address accessible on your iOS device.

Open the attachment

Open the email on your iPhone/iPad and tap the VCF attachment.

Import

Follow the same import flow as the AirDrop method.

Method 3: iCloud Sync

If you use iCloud for contacts, you can import on your Mac and let it sync:

Open Contacts on Mac

Launch the Contacts app on macOS.

Import file

Go to File → Import… and select recursers.vcf.

Wait for sync

iCloud will automatically sync the new contacts to all your devices.

Photos: iOS preserves the embedded profile photos. They’ll appear in your contact list and when making calls.

Categories: The batch information stored in CATEGORIES fields can be viewed in the contact details but iOS doesn’t support filtering by categories natively.

Web Interface

Open Google Contacts

Navigate to contacts.google.com.

Access Import

Click Import in the left sidebar.

Select file

Click Select file and choose recursers.vcf from your computer.

Start import

Click Import to begin the process.

Wait for processing

Google will display a progress indicator. Large files may take several minutes.

Review results

Google will show a summary of imported contacts. Review for any errors.

Using Google Workspace Admin

If you’re an admin importing for multiple users:

Access Admin Console

Go to admin.google.com.

Navigate to Directory

Directory → Users → [Select User] → User information → Contacts

Import contacts

Use the import feature to upload the VCF file.

File size limit: Google Contacts has a 25 MB limit per import. If your VCF file is larger, you may need to split it into multiple files.

Splitting Large Files

If you encounter size limits, split the VCF file:

# Split every 500 contacts (adjust as needed)
csplit -f recursers- -n 2 recursers.vcf '/BEGIN:VCARD/' '{*}'

Or use this Python script:

def split_vcf(filename, chunk_size=500):
    with open(filename, 'r') as f:
        content = f.read()
    
    vcards = content.split('BEGIN:VCARD')
    vcards = ['BEGIN:VCARD' + v for v in vcards[1:]]  # Skip first empty
    
    for i in range(0, len(vcards), chunk_size):
        chunk = vcards[i:i+chunk_size]
        with open(f'recursers_part_{i//chunk_size + 1}.vcf', 'w') as f:
            f.write(''.join(chunk))

split_vcf('recursers.vcf')

Photos: Google Contacts preserves embedded photos and displays them in the contact list.

Labels: The social media URLs (GitHub, Twitter, LinkedIn) are preserved with their custom labels.

Outlook Desktop (Windows/Mac)

Open Outlook

Launch the Outlook desktop application.

Go to People

Click the People icon in the bottom-left corner.

Access Import

Go to File → Open & Export → Import/Export.

Choose import type

Select “Import a vCard file (.vcf)” and click Next.

Select file

Browse to recursers.vcf and click OK.

Wait for completion

Outlook will process the file. This may take several minutes.

Outlook Web (Office 365)

Open Outlook Web

Navigate to outlook.office.com.

Go to People

Click the People icon (or app launcher → People).

Manage contacts

Click Manage → Import contacts.

Upload file

Choose “From a file” and upload recursers.vcf.

Start import

Click Import and wait for completion.

Multiple contacts: Outlook may prompt you to import each contact individually if the file format isn’t recognized correctly. This is rare with properly formatted vCard 3.0 files.

Categories: The batch information in the CATEGORIES field will appear as contact categories in Outlook, allowing you to filter by batch.

Import via Contacts App

Open Contacts

Launch the Contacts app on macOS.

Import file

Go to File → Import… (or press Cmd+I).

Select file

Choose recursers.vcf and click Open.

Wait for import

The import happens in the background. You’ll see new contacts appear gradually.

Verify

Once complete, search for a Recurser’s name to verify the import succeeded.

Command Line Import

For automation or scripting:

# Import to default contacts
contacts -i recursers.vcf

iCloud Sync: If you have iCloud Contacts enabled, the imported contacts will automatically sync to your other Apple devices.

Photos: macOS Contacts fully supports embedded photos and will display them in the contact list and contact cards.

CardDAV / CalDAV

For CardDAV-compatible services (Nextcloud, ownCloud, etc.):

Access web interface

Find contacts section

Navigate to the contacts or address book section.

Import

Look for an import option and upload recursers.vcf.

Thunderbird

Open Address Book

In Thunderbird, go to Tools → Address Book.

Import

Go to Tools → Import and select Address Books.

Choose format

Select vCard as the format and choose recursers.vcf.

Android Contacts

Transfer file

Copy recursers.vcf to your Android device via USB, email, or cloud storage.

Open file

Use a file manager to locate and tap the VCF file.

Import

Android will ask which account to import to. Choose Google to sync across devices or Phone for local storage only.

Updating Contacts

To update your contacts with the latest information:

Generate a fresh VCF file

Run the generator again to create an updated recursers.vcf:

cargo run --release

Import the new file

Follow the same import process for your platform. The unique IDs (recurser-{id}) ensure that:

Existing contacts are updated with new information
New Recursers are added
No duplicate contacts are created

Verify updates

Check a few contacts to confirm their information was updated.

Most contact managers use the UID field to match existing contacts. Since the generator uses UID:recurser-{id} (see main.rs:303), re-importing will update rather than duplicate.

Filtering and Organization

By Batch

All Recursers have batch information in their CATEGORIES field:

CATEGORIES:Recurser,Recurse W1'25,Recurse S2'23

You can use this to:

Filter by batch in contact managers that support category filtering
Create smart groups based on batch membership
Find all Recursers by filtering for the “Recurser” category

All social media links are included with custom labels:

GitHub: X-ABLabel:GitHub
Twitter: X-ABLabel:Twitter
LinkedIn: X-ABLabel:LinkedIn
Recurse Center: X-ABLabel:Recurse Center

Contact managers that support custom URL labels will display these appropriately.

Troubleshooting

Import failed: File too large

The VCF file may exceed your contact manager’s size limit. Solutions:

Google Contacts: Split the file into chunks under 25 MB (see splitting instructions above)
Outlook Web: Try using the desktop app instead
iOS: Use the macOS import + iCloud sync method instead of direct import

Photos not showing up

Some contact managers don’t support embedded photos in vCard 3.0 format:

Google Contacts: Fully supported
iOS/macOS Contacts: Fully supported
Outlook: Partially supported (may need to click “Download pictures”)
Android: Depends on manufacturer’s contacts app

If photos aren’t displaying, check your contact manager’s settings for “Show contact photos” or similar options.

Duplicate contacts created

If duplicates appear despite the UIDs:

Export your contacts before importing again
Delete the duplicates using your contact manager’s duplicate detection
Re-import - the UIDs should prevent future duplicates

Some older contact managers don’t properly honor the UID field.

Special characters display incorrectly

The generator escapes special characters per the vCard spec (see main.rs:94-99):

Backslashes: \\
Newlines: \n
Commas: \,
Semicolons: \;

If these appear literally in your contacts, your contact manager may not be properly parsing vCard escape sequences.

Import taking too long

Large VCF files can take several minutes to import:

Google Contacts: 3-5 minutes for 2,000+ contacts
iOS: 1-2 minutes for direct import
macOS: 2-4 minutes for large files
Outlook: 5-10 minutes for large files

Be patient and don’t interrupt the import process.

Privacy Considerations

The VCF file contains personal information for all Recursers including:

Email addresses
Phone numbers (if provided)
Social media profiles
Profile photos

Treat this file as sensitive data:

Don’t share it publicly
Don’t commit it to public repositories
Store it securely
Delete old versions when no longer needed

Next Steps

After importing:

Search for fellow Recursers by name or batch
Add custom notes to contacts you interact with
Create groups by batch or interest area
Set up reminders to reach out to people
Re-import periodically to get updates and new Recursers

Consider running the generator monthly or quarterly to keep your contacts up-to-date with new Recursers and profile changes.

Get Started

Guides

API Client

Reference

Overview

Import Instructions by Platform

Method 1: AirDrop (Recommended)

Method 2: Email

Method 3: iCloud Sync

Web Interface

Using Google Workspace Admin

Splitting Large Files

Outlook Desktop (Windows/Mac)

Outlook Web (Office 365)

Import via Contacts App

Command Line Import

CardDAV / CalDAV

Thunderbird

Android Contacts

Updating Contacts

Filtering and Organization

By Batch

Troubleshooting

Privacy Considerations

Next Steps

Build docs developers (and LLMs) love

Get Started

Guides

API Client

Reference

​Overview

​Import Instructions by Platform

​Method 1: AirDrop (Recommended)

​Method 2: Email

​Method 3: iCloud Sync

​Web Interface

​Using Google Workspace Admin

​Splitting Large Files

​Outlook Desktop (Windows/Mac)

​Outlook Web (Office 365)

​Import via Contacts App

​Command Line Import

​CardDAV / CalDAV

​Thunderbird

​Android Contacts

​Updating Contacts

​Filtering and Organization

​By Batch

​By Social Media

​Troubleshooting

​Privacy Considerations

​Next Steps

Build docs developers (and LLMs) love

Overview

Import Instructions by Platform

Method 1: AirDrop (Recommended)

Method 2: Email

Method 3: iCloud Sync

Web Interface

Using Google Workspace Admin

Splitting Large Files

Outlook Desktop (Windows/Mac)

Outlook Web (Office 365)

Import via Contacts App

Command Line Import

CardDAV / CalDAV

Thunderbird

Android Contacts

Updating Contacts

Filtering and Organization

By Batch

By Social Media

Troubleshooting

Privacy Considerations

Next Steps