Skip to main content

​
Overview

A Service is the top-level entity in GOV.UK Notify. Every notification you send belongs to a service. Services contain templates, API keys, team members, and configuration settings.

​
Service Structure

​
Core Properties

  • Name: Unique identifier for your service
  • Organisation: Optional link to a parent organisation
  • Created by: User who created the service
  • Organisation type: Determines billing and allowances (central government, local, NHS, etc.)
  • Active: Service can send notifications
  • Restricted: Trial mode - can only send to team members and guest list
  • Archived: Service is deactivated
Services have daily sending limits for each channel:
  • email_message_limit: Default 999,999,999
  • sms_message_limit: Default 999,999,999
  • letter_message_limit: Default 999,999,999
  • international_sms_message_limit: Default 250,000

​
Service Permissions

Services have granular permissions that control available features: 
# From app/constants.py
SERVICE_PERMISSION_TYPES = [
    "email",              # Can send emails
    "sms",                # Can send SMS
    "letter",             # Can send letters
    "international_sms",  # Can send international SMS
    "inbound_sms",        # Can receive SMS replies
    "email_auth",         # Email-based authentication
    "edit_folder_permissions",
    "international_letters",
    "sms_to_uk_landlines",
    "send_files_via_ui",
]

​
Service Lifecycle

1

Trial Mode

New services start in restricted mode:
  • Can only send to verified team members
  • Can add recipients to a guest list
  • Limited to testing templates
2

Go Live Request

To send to real users:
  • Submit a go-live request
  • Provide service details and volumes
  • Get approval from organisation or Notify team
3

Live Service

After approval:
  • restricted = false
  • go_live_at timestamp set
  • Can send to any recipient
  • Free annual SMS allowance applied

​
Service Configuration

​
Branding

Services can customize email and letter branding: 
# Service has email branding relationship
email_branding:
  - logo: URL to logo image
  - colour: Hex color code (#123456)
  - text: Organization name
  - brand_type: "org", "both", or "org_banner"

​
Email Sender Configuration

Services can customize the sender name in emails: 
# From app/models.py - Service model
service.name = "Tax Department"
service.custom_email_sender_name = "HMRC Tax Notifications"
# Results in: [email protected]

# Email sender local part is automatically normalized:
service.email_sender_local_part  # Auto-generated from custom name or service name

​
Guest List (Restricted Mode)

When in trial mode, use the guest list to test with specific recipients: 
# Guest list supports:
- email_type: Email addresses
- mobile_type: Phone numbers (validated)

# Recipients must match exactly for notifications to send
Guest list entries are validated on creation. Invalid email addresses or phone numbers will be rejected.

​
Service Relationships

​
Organisation

Services can belong to an organisation:
  • Inherits organisation branding by default
  • Organisation type affects free SMS allowance
  • Organisations can have multiple services

​
Users

Team members have specific permissions per service:
  • manage_users: Add/remove team members
  • manage_templates: Create/edit templates
  • manage_settings: Configure service settings
  • send_texts, send_emails, send_letters: Send notifications
  • manage_api_keys: Create/revoke API keys
  • view_activity: Read-only access

​
Templates

Each service has its own templates organized in folders:
  • Templates are service-specific
  • Can be organized in nested folders
  • Support version history

​
Rate Limiting

Services have a rate limit for API requests: 
# Default rate limit
service.rate_limit = 3000  # requests per minute

# This is configurable per service
# Contact Notify team to adjust if needed

​
Callback APIs

Services can configure webhooks for delivery receipts: 
# Service callback types from app/constants.py
class ServiceCallbackTypes:
    delivery_status = "delivery_status"    # Notification status updates
    complaint = "complaint"                # Email complaints (bounces)
    returned_letter = "returned_letter"    # Undeliverable letters
    inbound_sms = "inbound_sms"            # SMS replies
Callback URLs must use HTTPS and include a bearer token for authentication.

​
Code Example

Here’s the service model structure from the source code: 
# From app/models.py
class Service(db.Model):
    id: UUID
    name: str                    # Unique service name
    active: bool                 # Is service active?
    restricted: bool             # Trial mode?
    created_by_id: UUID         # Creator user ID
    
    # Message limits
    email_message_limit: int
    sms_message_limit: int
    letter_message_limit: int
    international_sms_message_limit: int
    
    # Configuration
    rate_limit: int             # API requests per minute
    organisation_id: UUID       # Parent organisation
    organisation_type: str      # central, local, nhs_central, etc.
    
    # Go-live tracking
    go_live_at: datetime
    go_live_user_id: UUID
    
    # Branding
    email_branding: EmailBranding
    letter_branding: LetterBranding
    
    # Relationships
    users: List[User]           # Team members
    templates: List[Template]   # Message templates
    api_keys: List[ApiKey]      # API credentials
    permissions: List[ServicePermission]

​
Best Practices

Naming

Choose a clear, descriptive name. It appears in email sender addresses and audit logs.

Permissions

Only enable permissions your service needs. Start minimal and add as required.

Guest List

Keep your guest list updated during development. Remove test entries before go-live.

Rate Limits

Monitor your sending patterns. Request limit increases before reaching capacity.

Build docs developers (and LLMs) love

Get started for freeTalk to us