Skip to content

Email Integration Guide

Overview

This guide explains how emails are automatically sent when users are invited to workspaces or projects.

Workspace Invitations

When you add a member to a workspace using the API, they automatically receive a professional email invitation.

API Endpoint

POST /api/workspaces/{workspace_id}/members/
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "user_email": "[email protected]",
  "role": "ADMIN"
}

What Happens

  1. User is added to workspace - Creates WorkspaceUser record with specified role
  2. Email is sent automatically - Invitee receives a beautiful HTML email with:
  3. Who invited them (your name)
  4. Workspace name
  5. Their role (OWNER, ADMIN, or VIEWER)
  6. Direct link to the workspace
  7. Instructions on getting started

Email Template

The invitation email (emails/team_invitation.html) includes:

  • Professional header with AppVector branding
  • Personal greeting addressing the invite
  • Clear information about the workspace and role
  • Call-to-action button to access the workspace
  • Expiration notice (invitation expires in 7 days)
  • Footer with support links

Example Email Content

Subject: You've been invited to join Acme Corp

Hi there,

John Doe has invited you to join the Acme Corp workspace on AppVector!

Invitation Details:
• Workspace: Acme Corp
• Role: ADMIN
• Invited By: John Doe
• Expires In: 7 days

As an ADMIN, you'll be able to collaborate with the team and access
shared projects and analytics.

[Accept Invitation Button]

If you don't have an AppVector account yet, you'll be prompted to
create one. It only takes a minute!

Note: This invitation link will expire in 7 days.

Project Sharing

When you share a project with a workspace member, they automatically receive a notification email.

API Endpoint

POST /api/workspaces/{workspace_id}/projects/{project_id}/share/
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "user_email": "[email protected]",
  "role": "VIEWER"
}

What Happens

  1. User is granted project access - Creates ProjectUserAccess record with specified role
  2. Email is sent automatically - User receives a notification email with:
  3. Project name
  4. Who shared it with them
  5. Their access level (ADMIN or VIEWER)
  6. Direct link to the project
  7. Explanation of what they can do

Email Template

The project shared email (emails/project_shared.html) includes:

  • Professional header with AppVector branding
  • Clear notification of project access
  • Project details (name, shared by, role)
  • Role explanation (what they can do)
  • Call-to-action button to open the project
  • Helpful tips on accessing the project

Example Email Content

Subject: Project Shared: WhatsApp Tracking

Hi Jane Smith,

John Doe has shared a project with you!

Project Details:
• Project: WhatsApp Tracking
• Shared By: John Doe
• Your Role: VIEWER

You now have VIEWER access to this project. You can view project
data and analytics.

[Open Project Button]

You can find this project in your workspace dashboard along with
any other projects you have access to.

Happy tracking!

Email Flow Diagrams

Workspace Invitation Flow

User adds member via API
    ↓
Backend validates user exists
    ↓
Backend creates WorkspaceUser record
    ↓
Backend sends invitation email
    ↓
Invitee receives email in inbox
    ↓
Invitee clicks "Accept Invitation"
    ↓
Invitee is taken to workspace

Project Sharing Flow

User shares project via API
    ↓
Backend validates user is workspace member
    ↓
Backend creates ProjectUserAccess record
    ↓
Backend sends notification email
    ↓
User receives email in inbox
    ↓
User clicks "Open Project"
    ↓
User is taken to project dashboard

Testing Email Integration

Development Mode (Console Backend)

By default, emails are printed to the console in development:

# .env
EMAIL_BACKEND=django.core.mail.backends.console.EmailBackend

# Start server
docker compose up

# Add a member - email will appear in terminal
curl -X POST http://localhost:8000/api/workspaces/{id}/members/ \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user_email": "[email protected]", "role": "ADMIN"}'

# Check terminal output for email content

Testing in Django Shell

# Start Django shell
docker compose run --rm web uv run python manage.py shell

# Test team invitation email
from services.email_service import send_team_invitation_email

send_team_invitation_email(
    invitee_email='[email protected]',
    inviter_name='John Doe',
    workspace_name='Test Workspace',
    role='ADMIN',
    invitation_url='http://localhost:3000/workspaces/123'
)

# Test project shared email
from services.email_service import send_project_shared_email

send_project_shared_email(
    user_email='[email protected]',
    user_name='Jane Smith',
    project_name='Test Project',
    shared_by='John Doe',
    role='VIEWER',
    project_url='http://localhost:3000/workspaces/123/projects/456'
)

Testing with Real Email

  1. Configure SMTP in .env:
EMAIL_BACKEND=django.core.mail.backends.smtp.EmailBackend
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USE_TLS=True
EMAIL_HOST_USER=[email protected]
EMAIL_HOST_PASSWORD=your-app-password
  1. Add a member via API
  2. Check the recipient's inbox for the email

Error Handling

Email Sending Failures

Emails are sent with error handling to ensure API requests don't fail:

try:
    send_team_invitation_email(...)
    logger.info(f"Invitation email sent to {user_email}")
except Exception as email_error:
    # Log error but don't fail the request
    logger.error(f"Failed to send invitation email: {email_error}")

What this means: - ✅ Member is still added to workspace even if email fails - ✅ Project access is still granted even if email fails - ✅ Errors are logged for debugging - ✅ API request returns success - ⚠️ Check logs if emails aren't being received

Common Issues

Email Not Received

Possible causes: 1. Email backend set to console (check .env) 2. SMTP credentials incorrect 3. Email provider blocking outgoing emails 4. Recipient email address incorrect 5. Email went to spam folder

Solution: - Check application logs: docker compose logs -f web | grep email - Verify EMAIL_BACKEND in .env - Test with Django shell (see above) - Check spam/junk folder

Possible cause: FRONTEND_URL not configured correctly

Solution: 

# In .env
FRONTEND_URL=http://localhost:3000  # Development
# FRONTEND_URL=https://app.yourdomain.com  # Production

Customizing Email Content

Modifying Templates

Email templates are located in core/templates/emails/:

core/templates/emails/
├── base.html                      # Base template (styling)
├── team_invitation.html           # Workspace invitation
└── project_shared.html            # Project shared notification

To customize:

  1. Edit the HTML template
  2. Update context variables in services/email_service.py
  3. Restart the server
  4. Test the changes

Adding Custom Variables

To add new information to emails:

  1. Update the function in services/email_service.py:
def send_team_invitation_email(
    invitee_email: str,
    inviter_name: str,
    workspace_name: str,
    role: str,
    invitation_url: str,
    custom_message: str = ""  # Add new parameter
) -> bool:
    return EmailService.send_template_email(
        to_email=invitee_email,
        subject=f"You've been invited to join {workspace_name}",
        template_name="emails/team_invitation.html",
        context={
            "inviter_name": inviter_name,
            "workspace_name": workspace_name,
            "role": role,
            "invitation_url": invitation_url,
            "custom_message": custom_message,  # Add to context
            "expires_in": "7 days"
        }
    )
  1. Update the template to use the new variable:
{% if custom_message %}
<div class="info-box">
    <p>{{ custom_message }}</p>
</div>
{% endif %}

Production Checklist

Before going live:

  • [ ] Configure production SMTP settings in .env
  • [ ] Set EMAIL_BACKEND to SMTP backend
  • [ ] Set FRONTEND_URL to production domain
  • [ ] Test email delivery to multiple providers (Gmail, Outlook, etc.)
  • [ ] Verify links work correctly
  • [ ] Check email appears correctly on mobile devices
  • [ ] Set up SPF, DKIM, and DMARC DNS records
  • [ ] Monitor email delivery logs
  • [ ] Set up email alerts for failures

Email Tracking & Analytics

Viewing Logs

# View all email-related logs
docker compose logs -f web | grep -i email

# View invitation emails sent
docker compose logs -f web | grep "Invitation email sent"

# View project sharing emails sent
docker compose logs -f web | grep "Project shared email sent"

# View email errors
docker compose logs -f web | grep "Failed to send.*email"

Example Log Output

INFO Invitation email sent to [email protected] for workspace Acme Corp
INFO Project shared email sent to [email protected] for project WhatsApp Tracking
ERROR Failed to send invitation email to [email protected]: SMTP Error

API Response Examples

Successful Workspace Invitation

HTTP 201 Created

{
  "id": "uuid",
  "workspace_id": "workspace-uuid",
  "user": {
    "id": "user-uuid",
    "email": "[email protected]",
    "first_name": "Jane",
    "last_name": "Smith"
  },
  "role": "ADMIN",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Note: Email is sent in the background. Success response means user was added; check logs for email status.

Successful Project Sharing

HTTP 201 Created

{
  "id": "uuid",
  "user": {
    "id": "user-uuid",
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe"
  },
  "role": "VIEWER",
  "created_at": "2024-01-15T10:35:00Z",
  "updated_at": "2024-01-15T10:35:00Z"
}

Note: Email is sent in the background. Success response means access granted; check logs for email status.

Summary

✅ Automatic email notifications when users are invited to workspaces or projects ✅ Professional HTML templates with consistent branding ✅ Error-resilient - API requests succeed even if emails fail ✅ Development-friendly - Console backend for local testing ✅ Production-ready - SMTP backend for real email delivery ✅ Customizable - Easy to modify templates and content ✅ Well-logged - All email activity logged for debugging

Users will love receiving clear, professional notifications when they're invited to collaborate!