utilities¶

Through the REST api you are able to call a subset of the SP.Utilities.Utility methods. We have explicitly defined some of these methods and provided a method to call any others in a generic manner. These methods are exposed on pnp.sp.utility and support batching and caching.

sendEmail¶

⚠️ Deprecated: This method is deprecated in favor of the Graph module's sendMessage. Please migrate to the Graph module for sending emails. This functionality will be removed in future versions.

This methods allows you to send an email based on the supplied arguments. The method takes a single argument, a plain object defined by the EmailProperties interface (shown below).

EmailProperties¶

export interface TypedHash<T> {
    [key: string]: T;
}

export interface EmailProperties {

    To: string[];
    CC?: string[];
    BCC?: string[];
    Subject: string;
    Body: string;
    AdditionalHeaders?: TypedHash<string>;
    From?: string;
}

Usage¶

You must define the To, Subject, and Body values - the remaining are optional.

import { spfi } from "@pnp/sp";
import "@pnp/sp/sputilities";
import { IEmailProperties } from "@pnp/sp/sputilities";

const sp = spfi(...);

const emailProps: IEmailProperties = {
    To: ["user@site.com"],
    CC: ["user2@site.com", "user3@site.com"],
    BCC: ["user4@site.com", "user5@site.com"],
    Subject: "This email is about...",
    Body: "Here is the body. <b>It supports html</b>",
    AdditionalHeaders: {
        "content-type": "text/html"
    }
};

await sp.utility.sendEmail(emailProps);
console.log("Email Sent!");

getCurrentUserEmailAddresses¶

This method returns the current user's email addresses known to SharePoint.

import { spfi } from "@pnp/sp";
import "@pnp/sp/sputilities";

const sp = spfi(...);

let addressString: string = await sp.utility.getCurrentUserEmailAddresses();

// and use it with sendEmail 
// note: sendEmail has been deprecated in favor of Graph module's sendMessage functionality
await sp.utility.sendEmail({
    To: [addressString],
    Subject: "This email is about...",
    Body: "Here is the body. <b>It supports html</b>",
    AdditionalHeaders: {
        "content-type": "text/html"
    },
});

resolvePrincipal¶

Gets information about a principal that matches the specified Search criteria

import { spfi, SPFx, IPrincipalInfo, PrincipalType, PrincipalSource } from "@pnp/sp";
import "@pnp/sp/sputilities";

const sp = spfi(...);

let principal : IPrincipalInfo = await sp.utility.resolvePrincipal("user@site.com", PrincipalType.User, PrincipalSource.All, true, false, true);

console.log(principal);

searchPrincipals¶

Gets information about the principals that match the specified Search criteria.

import { spfi, SPFx, IPrincipalInfo, PrincipalType, PrincipalSource } from "@pnp/sp";
import "@pnp/sp/sputilities";

const sp = spfi(...);

let principals : IPrincipalInfo[] = await sp.utility.searchPrincipals("john", PrincipalType.User, PrincipalSource.All,"", 10);

console.log(principals);

createEmailBodyForInvitation¶

Gets the external (outside the firewall) URL to a document or resource in a site.

import { spfi } from "@pnp/sp";
import "@pnp/sp/sputilities";

const sp = spfi(...);

let url : string = await sp.utility.createEmailBodyForInvitation("https://contoso.sharepoint.com/sites/dev/SitePages/DevHome.aspx");
console.log(url);

expandGroupsToPrincipals¶

Resolves the principals contained within the supplied groups

import { spfi, SPFx, IPrincipalInfo } from "@pnp/sp";
import "@pnp/sp/sputilities";

const sp = spfi(...);

let principals : IPrincipalInfo[] = await sp.utility.expandGroupsToPrincipals(["Dev Owners", "Dev Members"]);
console.log(principals);

// optionally supply a max results count. Default is 30.
let principals : IPrincipalInfo[] = await sp.utility.expandGroupsToPrincipals(["Dev Owners", "Dev Members"], 10);
console.log(principals);

createWikiPage¶

import { spfi } from "@pnp/sp";
import "@pnp/sp/sputilities";
import { ICreateWikiPageResult } from "@pnp/sp/sputilities";

const sp = spfi(...);

let newPage : ICreateWikiPageResult = await sp.utility.createWikiPage({
    ServerRelativeUrl: "/sites/dev/SitePages/mynewpage.aspx",
    WikiHtmlContent: "This is my <b>page</b> content. It supports rich html.",
});

// newPage contains the raw data returned by the service
console.log(newPage.data);

// newPage contains a File instance you can use to further update the new page
let file = await newPage.file();
console.log(file);