Add Templates resources for the paginated /api/templates endpoints

Mailtrap.sln

@@ -102,6 +102,8 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Mailtrap.Example.ContactEve
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Mailtrap.Example.EmailTemplates", "examples\Mailtrap.Example.EmailTemplates\Mailtrap.Example.EmailTemplates.csproj", "{A52169E1-8653-4B7D-9F14-84837E237E43}"
 EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Mailtrap.Example.Templates", "examples\Mailtrap.Example.Templates\Mailtrap.Example.Templates.csproj", "{9A59D8CF-688C-4DA6-9CF6-F9C892783910}"
+EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Mailtrap.Example.Email.BatchSend", "examples\Mailtrap.Example.Email.BatchSend\Mailtrap.Example.Email.BatchSend.csproj", "{9922946A-03DA-4AC6-8AA6-ADEC5EF2E9EB}"
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Mailtrap.Example.ContactExports", "examples\Mailtrap.Example.ContactExports\Mailtrap.Example.ContactExports.csproj", "{8791C343-7B1E-4206-A954-A0CFD573E460}"
@@ -422,6 +424,18 @@ Global
 		{A52169E1-8653-4B7D-9F14-84837E237E43}.Release|x64.Build.0 = Release|Any CPU
 		{A52169E1-8653-4B7D-9F14-84837E237E43}.Release|x86.ActiveCfg = Release|Any CPU
 		{A52169E1-8653-4B7D-9F14-84837E237E43}.Release|x86.Build.0 = Release|Any CPU
+		{9A59D8CF-688C-4DA6-9CF6-F9C892783910}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{9A59D8CF-688C-4DA6-9CF6-F9C892783910}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{9A59D8CF-688C-4DA6-9CF6-F9C892783910}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{9A59D8CF-688C-4DA6-9CF6-F9C892783910}.Debug|x64.Build.0 = Debug|Any CPU
+		{9A59D8CF-688C-4DA6-9CF6-F9C892783910}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{9A59D8CF-688C-4DA6-9CF6-F9C892783910}.Debug|x86.Build.0 = Debug|Any CPU
+		{9A59D8CF-688C-4DA6-9CF6-F9C892783910}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{9A59D8CF-688C-4DA6-9CF6-F9C892783910}.Release|Any CPU.Build.0 = Release|Any CPU
+		{9A59D8CF-688C-4DA6-9CF6-F9C892783910}.Release|x64.ActiveCfg = Release|Any CPU
+		{9A59D8CF-688C-4DA6-9CF6-F9C892783910}.Release|x64.Build.0 = Release|Any CPU
+		{9A59D8CF-688C-4DA6-9CF6-F9C892783910}.Release|x86.ActiveCfg = Release|Any CPU
+		{9A59D8CF-688C-4DA6-9CF6-F9C892783910}.Release|x86.Build.0 = Release|Any CPU
 		{9922946A-03DA-4AC6-8AA6-ADEC5EF2E9EB}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
 		{9922946A-03DA-4AC6-8AA6-ADEC5EF2E9EB}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{9922946A-03DA-4AC6-8AA6-ADEC5EF2E9EB}.Debug|x64.ActiveCfg = Debug|Any CPU
@@ -583,6 +597,7 @@ Global
 		{5CEEEC08-7F1F-4F75-BC8D-6E80C54C21FD} = {09E18837-1DDE-4EAF-80EC-DA55557C81EB}
 		{AA91FC07-FE50-4DE1-A388-7AA0DB35C84A} = {09E18837-1DDE-4EAF-80EC-DA55557C81EB}
 		{A52169E1-8653-4B7D-9F14-84837E237E43} = {09E18837-1DDE-4EAF-80EC-DA55557C81EB}
+		{9A59D8CF-688C-4DA6-9CF6-F9C892783910} = {09E18837-1DDE-4EAF-80EC-DA55557C81EB}
 		{9922946A-03DA-4AC6-8AA6-ADEC5EF2E9EB} = {09E18837-1DDE-4EAF-80EC-DA55557C81EB}
 		{8791C343-7B1E-4206-A954-A0CFD573E460} = {09E18837-1DDE-4EAF-80EC-DA55557C81EB}
 		{11894B20-F780-4FC9-8140-3601EBF54C10} = {09E18837-1DDE-4EAF-80EC-DA55557C81EB}

README.md

@@ -308,6 +308,7 @@ private static SendEmailRequest TemplateBasedRequest()
 
 ### General
 
+- Templates management (experimental) – [`examples/Mailtrap.Example.Templates`](examples/Mailtrap.Example.Templates/)
 - Email Templates management – [`examples/Mailtrap.Example.EmailTemplates`](examples/Mailtrap.Example.EmailTemplates/)
 - Account access management – [`examples/Mailtrap.Example.AccountAccess`](examples/Mailtrap.Example.AccountAccess/)
 - Permissions management – [`examples/Mailtrap.Example.Permissions`](examples/Mailtrap.Example.Permissions/)

examples/Mailtrap.Example.Templates/Mailtrap.Example.Templates.csproj

@@ -0,0 +1 @@
+<Project Sdk="Microsoft.NET.Sdk" />

examples/Mailtrap.Example.Templates/Program.cs

@@ -0,0 +1,77 @@
+using Mailtrap;
+using Mailtrap.Accounts;
+using Mailtrap.Templates;
+using Mailtrap.Templates.Models;
+using Mailtrap.Templates.Requests;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+
+
+HostApplicationBuilder hostBuilder = Host.CreateApplicationBuilder(args);
+
+IConfigurationSection config = hostBuilder.Configuration.GetSection("Mailtrap");
+
+hostBuilder.Services.AddMailtrapClient(config);
+
+using IHost host = hostBuilder.Build();
+
+ILogger<Program> logger = host.Services.GetRequiredService<ILogger<Program>>();
+IMailtrapClient mailtrapClient = host.Services.GetRequiredService<IMailtrapClient>();
+
+try
+{
+    var accountId = 12345;
+    IAccountResource accountResource = mailtrapClient.Account(accountId);
+
+    // Get resource for templates collection
+    ITemplateCollectionResource templatesResource = accountResource.Templates();
+
+    // Get the first page of templates, 50 per page
+    var filter = new TemplateListFilter { Token = 1, PerPage = 50 };
+    TemplateList page = await templatesResource.GetAll(filter);
+
+    logger.LogInformation("Found {Count} templates on the first page.", page.Data.Count);
+    logger.LogInformation("Next page token: {NextToken}", page.Pagination?.NextToken);
+
+    // Create a dedicated template so the update and delete below never touch an existing one
+    var createTemplateRequest = new CreateTemplateRequest
+    {
+        Name = "MyFirstTemplate",
+        Category = "TestCategory",
+        Subject = "TestSubject",
+        BodyHtml = "<h1>This is HTML body</h1>",
+        BodyText = "This is text body"
+    };
+    Template template = await templatesResource.Create(createTemplateRequest);
+    logger.LogInformation("Created template {Name} with Id {Id}.", template.Name, template.Id);
+
+    // Get resource for specific template
+    ITemplateResource templateResource = accountResource.Template(template.Id);
+
+    // Get details
+    Template templateResponse = await templateResource.GetDetails();
+    logger.LogInformation("Template Name from resource: {Name}", templateResponse.Name);
+    logger.LogInformation("Template Id from resource: {Id}", templateResponse.Id);
+
+    // Update template details, only the properties that are set are changed
+    var updateTemplateRequest = new UpdateTemplateRequest
+    {
+        Name = "updatedTemplate",
+        BodyHtml = "<h1>This is updated HTML body</h1>"
+    };
+    Template updateTemplateResponse = await templateResource.Update(updateTemplateRequest);
+    logger.LogInformation("Updated Template: Name={Name}, Id={Id}", updateTemplateResponse.Name, updateTemplateResponse.Id);
+
+    // Delete template
+    // Beware that template resource becomes invalid after deletion and should not be used anymore
+    await templateResource.Delete();
+    logger.LogInformation("Template Deleted.");
+}
+catch (Exception ex)
+{
+    logger.LogError(ex, "An error occurred during API call.");
+    Environment.ExitCode = 1;
+    return;
+}

examples/Mailtrap.Example.Templates/Properties/launchSettings.json

@@ -0,0 +1,10 @@
+{
+  "profiles": {
+    "Project": {
+      "commandName": "Project",
+      "environmentVariables": {
+        "DOTNET_ENVIRONMENT": "Development"
+      }
+    }
+  }
+}

examples/Mailtrap.Example.Templates/appsettings.json

@@ -0,0 +1,17 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "System": "Warning",
+      "Microsoft": "Warning"
+    },
+    "Debug": {
+      "LogLevel": {
+        "Default": "Debug"
+      }
+    }
+  },
+  "Mailtrap": {
+    "ApiToken": "<API_KEY>"
+  }
+}

src/Mailtrap.Abstractions/Accounts/IAccountResource.cs

@@ -162,6 +162,9 @@ public interface IAccountResource : IRestResource
     /// <summary>
     /// Gets email template collection resource for the account, represented by this resource instance.
     /// </summary>
+    /// <remarks>
+    /// For the paginated, experimental <c>/api/templates</c> endpoints, see <see cref="Templates"/>.
+    /// </remarks>
     ///
     /// <returns>
     /// Email template collection resource for the account, represented by this resource instance.
@@ -185,6 +188,42 @@ public interface IAccountResource : IRestResource
     /// </exception>
     public IEmailTemplateResource EmailTemplate(long emailTemplateId);
 
+    /// <summary>
+    /// Gets template collection resource for the account, represented by this resource instance.
+    /// </summary>
+    ///
+    /// <remarks>
+    /// The <c>/api/templates</c> endpoints are experimental: their request and response shapes may change
+    /// before general availability.
+    /// </remarks>
+    ///
+    /// <returns>
+    /// Template collection resource for the account, represented by this resource instance.
+    /// </returns>
+    public ITemplateCollectionResource Templates();
+
+    /// <summary>
+    /// Gets resource for specific template, identified by <paramref name="templateId"/>.
+    /// </summary>
+    ///
+    /// <remarks>
+    /// The <c>/api/templates</c> endpoints are experimental: their request and response shapes may change
+    /// before general availability.
+    /// </remarks>
+    ///
+    /// <param name="templateId">
+    /// ID of template to get resource for.
+    /// </param>
+    ///
+    /// <returns>
+    /// Resource for the template with specified ID.
+    /// </returns>
+    ///
+    /// <exception cref="ArgumentOutOfRangeException">
+    /// When <paramref name="templateId"/> is less than or equal to zero.
+    /// </exception>
+    public ITemplateResource Template(long templateId);
+
     /// <summary>
     /// Gets suppression collection resource for the account, represented by this resource instance.
     /// </summary>

src/Mailtrap.Abstractions/GlobalUsings.cs

@@ -95,6 +95,10 @@
 global using Mailtrap.Suppressions.Models;
 global using Mailtrap.Suppressions.Requests;
 global using Mailtrap.Suppressions.Validators;
+global using Mailtrap.Templates;
+global using Mailtrap.Templates.Models;
+global using Mailtrap.Templates.Requests;
+global using Mailtrap.Templates.Validators;
 global using Mailtrap.TrackingOptOuts;
 global using Mailtrap.TrackingOptOuts.Models;
 global using Mailtrap.TrackingOptOuts.Requests;

src/Mailtrap.Abstractions/Templates/ITemplateCollectionResource.cs

@@ -0,0 +1,45 @@
+namespace Mailtrap.Templates;
+
+
+/// <summary>
+/// Represents the templates collection resource, served by the paginated <c>/api/templates</c> endpoints.
+/// </summary>
+/// <remarks>
+/// The endpoints are experimental: their request and response shapes may change before general availability.
+/// </remarks>
+public interface ITemplateCollectionResource : IRestResource
+{
+    /// <summary>
+    /// Gets a page of template details.
+    /// </summary>
+    ///
+    /// <param name="filter">
+    /// Pagination parameters, or <see langword="null"/> to get the first page with the default page size.
+    /// </param>
+    ///
+    /// <param name="cancellationToken">
+    /// Token to control operation cancellation.
+    /// </param>
+    ///
+    /// <returns>
+    /// Page of template details with pagination metadata.
+    /// </returns>
+    public Task<TemplateList> GetAll(TemplateListFilter? filter = null, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Creates a new template with details specified by <paramref name="request"/>.
+    /// </summary>
+    ///
+    /// <param name="request">
+    /// Request containing template details for creation.
+    /// </param>
+    ///
+    /// <param name="cancellationToken">
+    /// <inheritdoc cref="GetAll(TemplateListFilter?, CancellationToken)" path="/param[@name='cancellationToken']"/>
+    /// </param>
+    ///
+    /// <returns>
+    /// Created template details.
+    /// </returns>
+    public Task<Template> Create(CreateTemplateRequest request, CancellationToken cancellationToken = default);
+}

src/Mailtrap.Abstractions/Templates/ITemplateResource.cs

@@ -0,0 +1,61 @@
+namespace Mailtrap.Templates;
+
+
+/// <summary>
+/// Represents Template resource, served by the <c>/api/templates</c> endpoints.
+/// </summary>
+/// <remarks>
+/// The endpoints are experimental: their request and response shapes may change before general availability.
+/// </remarks>
+public interface ITemplateResource : IRestResource
+{
+    /// <summary>
+    /// Gets details of the template, represented by the current resource instance.
+    /// </summary>
+    ///
+    /// <param name="cancellationToken">
+    /// Token to control operation cancellation.
+    /// </param>
+    ///
+    /// <returns>
+    /// Requested template details.
+    /// </returns>
+    public Task<Template> GetDetails(CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Updates the template, represented by the current resource instance, with details specified by <paramref name="request"/>.
+    /// </summary>
+    ///
+    /// <param name="request">
+    /// Template details for update.
+    /// </param>
+    ///
+    /// <param name="cancellationToken">
+    /// <inheritdoc cref="GetDetails(CancellationToken)" path="/param[@name='cancellationToken']"/>
+    /// </param>
+    ///
+    /// <returns>
+    /// Updated template details.
+    /// </returns>
+    public Task<Template> Update(UpdateTemplateRequest request, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Deletes the template, represented by the current resource instance.
+    /// </summary>
+    ///
+    /// <param name="cancellationToken">
+    /// <inheritdoc cref="GetDetails(CancellationToken)" path="/param[@name='cancellationToken']"/>
+    /// </param>
+    ///
+    /// <returns>
+    /// Nothing is returned upon successful deletion.
+    /// </returns>
+    ///
+    /// <remarks>
+    /// <para>
+    /// After deletion of the template, represented by the current resource instance, it will no longer be available.<br />
+    /// Thus any further operations on it will result in an error.
+    /// </para>
+    /// </remarks>
+    public Task Delete(CancellationToken cancellationToken = default);
+}