Msg.Extensions (msg v0.3.8)

Manage open extensions on Microsoft Graph resources.

Open extensions allow adding custom properties to Microsoft Graph resources (events, tasks, messages, etc.). Applications can use this to tag resources with custom metadata for synchronization and tracking.

Background

Open extensions are schema-less JSON objects attached to Graph resources. Each extension must have a unique extensionName (typically in reverse DNS format) and can contain any custom properties.

Required Permissions

Permissions depend on the resource type being extended:

  • Calendar Events: Calendars.ReadWrite (application) or Calendars.ReadWrite (delegated)
  • Messages: Mail.ReadWrite (application) or Mail.ReadWrite (delegated)
  • Tasks: Tasks.ReadWrite.All (application) or Tasks.ReadWrite (delegated)

Examples

# Create extension on a calendar event
{:ok, ext} = Msg.Extensions.create(
  client,
  "/users/user@contoso.com/events/AAMkAGI...",
  "com.example.metadata",
  %{project_id: "proj_123", resource_id: "res_456"}
)

# Get specific extension
{:ok, ext} = Msg.Extensions.get(
  client,
  "/users/user@contoso.com/events/AAMkAGI...",
  "com.example.metadata"
)

# Update extension properties
{:ok, updated} = Msg.Extensions.update(
  client,
  "/users/user@contoso.com/events/AAMkAGI...",
  "com.example.metadata",
  %{project_id: "proj_456"}
)

# Delete extension
:ok = Msg.Extensions.delete(
  client,
  "/users/user@contoso.com/events/AAMkAGI...",
  "com.example.metadata"
)

References

Summary

Functions

create(client, resource_path, extension_name, properties)

Creates an open extension on a Microsoft Graph resource.

delete(client, resource_path, extension_name)

Deletes an extension from a resource.

get(client, resource_path, extension_name)

Gets a specific extension by ID.

list(client, resource_path)

Lists all extensions on a resource.

update(client, resource_path, extension_name, updates)

Updates an extension's properties.

Functions

create(client, resource_path, extension_name, properties)

@spec create(Req.Request.t(), String.t(), String.t(), map()) ::
  {:ok, map()} | {:error, term()}

Creates an open extension on a Microsoft Graph resource.

Parameters

  • client - Authenticated Req.Request client
  • resource_path - Path to resource (e.g., "/users/user@contoso.com/events/AAMkAGI...")
  • extension_name - Unique name in reverse DNS format (e.g., "com.example.metadata")
  • properties - Map of custom properties

Returns

  • {:ok, extension} - Created extension with all properties
  • {:error, :unauthorized} - Invalid or expired token
  • {:error, {:invalid_request, message}} - Validation error
  • {:error, term} - Other errors

Examples

{:ok, ext} = Msg.Extensions.create(
  client,
  "/users/user@contoso.com/events/AAMkAGI...",
  "com.example.metadata",
  %{project_id: "proj_123", resource_id: "res_456", priority: "high"}
)

delete(client, resource_path, extension_name)

@spec delete(Req.Request.t(), String.t(), String.t()) :: :ok | {:error, term()}

Deletes an extension from a resource.

Parameters

  • client - Authenticated Req.Request client
  • resource_path - Path to resource
  • extension_name - Name/ID of the extension to delete

Returns

  • :ok - Extension deleted successfully (204 status)
  • {:error, :not_found} - Extension doesn't exist
  • {:error, term} - Other errors

Examples

:ok = Msg.Extensions.delete(
  client,
  "/users/user@contoso.com/events/AAMkAGI...",
  "com.example.metadata"
)

get(client, resource_path, extension_name)

@spec get(Req.Request.t(), String.t(), String.t()) :: {:ok, map()} | {:error, term()}

Gets a specific extension by ID.

Parameters

  • client - Authenticated Req.Request client
  • resource_path - Path to resource
  • extension_name - Name/ID of the extension to retrieve

Returns

  • {:ok, extension} - Extension map with all properties
  • {:error, :not_found} - Extension doesn't exist
  • {:error, term} - Other errors

Examples

{:ok, ext} = Msg.Extensions.get(
  client,
  "/users/user@contoso.com/events/AAMkAGI...",
  "com.example.metadata"
)

project_id = ext["projectId"]

list(client, resource_path)

@spec list(Req.Request.t(), String.t()) :: {:ok, [map()]} | {:error, term()}

Lists all extensions on a resource.

Note: Not all Microsoft Graph resource types support listing extensions. Calendar events, for example, require retrieving extensions by ID.

Parameters

  • client - Authenticated Req.Request client
  • resource_path - Path to resource

Returns

  • {:ok, [extension]} - List of extensions
  • {:error, :method_not_allowed} - Resource type doesn't support listing
  • {:error, term} - Other errors

Examples

# May not work for all resource types
{:ok, extensions} = Msg.Extensions.list(
  client,
  "/users/user@contoso.com/messages/AAMkAGI..."
)

update(client, resource_path, extension_name, updates)

@spec update(Req.Request.t(), String.t(), String.t(), map()) ::
  {:ok, map()} | {:error, term()}

Updates an extension's properties.

Warning: Microsoft Graph does not support PATCH updates on open extensions for all resource types. This function is provided for completeness, but may not work for calendar events and other resources. To "update" an extension, you typically need to delete and recreate it.

Parameters

  • client - Authenticated Req.Request client
  • resource_path - Path to resource
  • extension_name - Name/ID of the extension
  • updates - Map of properties to update

Returns

  • {:ok, extension} - Updated extension (if supported by resource type)
  • {:error, :not_found} - Extension doesn't exist
  • {:error, {:graph_api_error, _}} - Update not supported for this resource type
  • {:error, term} - Other errors

Examples

# This may not work for calendar events
{:ok, updated} = Msg.Extensions.update(
  client,
  "/users/user@contoso.com/messages/AAMkAGI...",
  "com.example.metadata",
  %{priority: "urgent"}
)