Feature/124 contact lists

Mailtrap.sln

@@ -89,6 +89,10 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Mailtrap.Example.Factory",
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Mailtrap.Example.Contact", "examples\Mailtrap.Example.Contact\Mailtrap.Example.Contact.csproj", "{3F8D2B21-5C6E-4A9A-9C3B-9F1D2A7B8C64}"
 EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Mailtrap.Example.ContactImports", "examples\Mailtrap.Example.ContactImports\Mailtrap.Example.ContactImports.csproj", "{E7B8C1F2-9A3D-4C2E-8B7A-6D2F3A1E4B5C}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Mailtrap.Example.ContactLists", "examples\Mailtrap.Example.ContactLists\Mailtrap.Example.ContactLists.csproj", "{08B23D8C-7AAC-4CE7-830C-4DFF9F296BFB}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -167,6 +171,14 @@ Global
 		{3F8D2B21-5C6E-4A9A-9C3B-9F1D2A7B8C64}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{3F8D2B21-5C6E-4A9A-9C3B-9F1D2A7B8C64}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{3F8D2B21-5C6E-4A9A-9C3B-9F1D2A7B8C64}.Release|Any CPU.Build.0 = Release|Any CPU
+		{E7B8C1F2-9A3D-4C2E-8B7A-6D2F3A1E4B5C}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{E7B8C1F2-9A3D-4C2E-8B7A-6D2F3A1E4B5C}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{E7B8C1F2-9A3D-4C2E-8B7A-6D2F3A1E4B5C}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{E7B8C1F2-9A3D-4C2E-8B7A-6D2F3A1E4B5C}.Release|Any CPU.Build.0 = Release|Any CPU
+		{08B23D8C-7AAC-4CE7-830C-4DFF9F296BFB}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{08B23D8C-7AAC-4CE7-830C-4DFF9F296BFB}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{08B23D8C-7AAC-4CE7-830C-4DFF9F296BFB}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{08B23D8C-7AAC-4CE7-830C-4DFF9F296BFB}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -190,6 +202,8 @@ Global
 		{F6357CAB-06C6-4603-99E7-1EDB79ACA8E8} = {09E18837-1DDE-4EAF-80EC-DA55557C81EB}
 		{AB1237F4-D074-4D3C-9AE4-6794BD30EA71} = {09E18837-1DDE-4EAF-80EC-DA55557C81EB}
 		{3F8D2B21-5C6E-4A9A-9C3B-9F1D2A7B8C64} = {09E18837-1DDE-4EAF-80EC-DA55557C81EB}
+		{E7B8C1F2-9A3D-4C2E-8B7A-6D2F3A1E4B5C} = {09E18837-1DDE-4EAF-80EC-DA55557C81EB}
+		{08B23D8C-7AAC-4CE7-830C-4DFF9F296BFB} = {09E18837-1DDE-4EAF-80EC-DA55557C81EB}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {0FF614CC-FEBC-4C66-B3FC-FCB73EE511D7}

examples/Mailtrap.Example.ContactImports/Mailtrap.Example.ContactImports.csproj

@@ -0,0 +1,11 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.Http" VersionOverride="9.0.8" />
+    <PackageReference Include="System.Text.Json" VersionOverride="9.0.7" />
+  </ItemGroup>
+  <ItemGroup>
+    <Content Include="appsettings.json">
+      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+    </Content>
+  </ItemGroup>
+</Project>

examples/Mailtrap.Example.ContactImports/Program.cs

@@ -0,0 +1,69 @@
+using Mailtrap;
+using Mailtrap.Accounts;
+using Mailtrap.Contacts;
+using Mailtrap.Contacts.Requests;
+using Mailtrap.ContactImports;
+using Mailtrap.ContactImports.Models;
+using Mailtrap.ContactImports.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 contacts collection
+    IContactCollectionResource contactsResource = accountResource.Contacts();
+
+    //Get resource for contact imports collection
+    IContactsImportCollectionResource contactsImportsResource = contactsResource.Imports();
+
+    // Prepare list of contacts to import
+    var contactImportList = new List<ContactImportRequest>
+    {
+        new("[email protected]"),
+        new("[email protected]"),
+        new("[email protected]"),
+    };
+
+    // Create contacts import request
+    var importRequest = new ContactsImportRequest(contactImportList);
+
+    // Import contacts in bulk
+    ContactsImport importResponse = await contactsImportsResource.Create(importRequest);
+    logger.LogInformation("Created contact import: {Import}", importResponse);
+
+    // Get resource for specific contact import
+    IContactsImportResource contactsImportResource = contactsResource.Import(importResponse.Id);
+
+    // Get details of specific contact import
+    ContactsImport contactsImportDetails = await contactsImportResource.GetDetails();
+    logger.LogInformation("Contacts Import Details: {Details}", contactsImportDetails);
+
+    if (contactsImportDetails.Status == ContactsImportStatus.Failed)
+    {
+        logger.LogWarning("Import failed!");
+    }
+}
+catch (Exception ex)
+{
+    logger.LogError(ex, "An error occurred during API call.");
+    Environment.FailFast(ex.Message);
+    throw;
+}

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

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

examples/Mailtrap.Example.ContactImports/appsettings.json

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

examples/Mailtrap.Example.ContactLists/Mailtrap.Example.ContactLists.csproj

@@ -0,0 +1,11 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.Http" VersionOverride="9.0.8" />
+    <PackageReference Include="System.Text.Json" VersionOverride="9.0.7" />
+  </ItemGroup>
+  <ItemGroup>
+    <Content Include="appsettings.json">
+      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+    </Content>
+  </ItemGroup>
+</Project>

examples/Mailtrap.Example.ContactLists/Program.cs

@@ -0,0 +1,75 @@
+using Mailtrap;
+using Mailtrap.Accounts;
+using Mailtrap.Contacts;
+using Mailtrap.ContactLists;
+using Mailtrap.ContactLists.Models;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+using Mailtrap.ContactLists.Requests;
+
+
+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 contacts collection
+    IContactCollectionResource contactsResource = accountResource.Contacts();
+
+    // Get resource for contacts list collection
+    IContactsListCollectionResource contactsListsResource = contactsResource.Lists();
+
+    // Get all contacts lists for account
+    IList<ContactsList> contactsLists = await contactsListsResource.GetAll();
+
+    ContactsList? contactsList = contactsLists.Count > 0 ? contactsLists[0] : null;
+
+    if (contactsList is null)
+    {
+        logger.LogWarning("No contacts list found. Creating.");
+
+        // Create contacts list
+        var createContactsListRequest = new ContactsListRequest("MyFirstContactsList");
+        contactsList = await contactsListsResource.Create(createContactsListRequest);
+    }
+    else
+    {
+        logger.LogInformation("Contacts List {Name} found.", contactsList.Name);
+    }
+
+    // Get resource for specific contacts list
+    IContactsListResource contactsListResource = contactsResource.List(contactsList.Id);
+
+    // Get details
+    ContactsList contactsListResponse = await contactsListResource.GetDetails();
+    logger.LogInformation("Contacts List from resource: {Name}", contactsListResponse.Name);
+
+    // Update contacts list details
+    var updateContactsListRequest = new ContactsListRequest("updatedContactsList");
+    ContactsList updateContactsListResponse = await contactsListResource.Update(updateContactsListRequest);
+    logger.LogInformation("Updated Contacts List: Name={Name}, Id={Id}", updateContactsListResponse.Name, updateContactsListResponse.Id);
+
+    // Delete contacts List
+    // Beware that contacts list resource becomes invalid after deletion and should not be used anymore
+    await contactsListResource.Delete();
+    logger.LogInformation("Contacts List Deleted.");
+}
+catch (Exception ex)
+{
+    logger.LogError(ex, "An error occurred during API call.");
+    Environment.ExitCode = 1;
+    return;
+}

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

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

examples/Mailtrap.Example.ContactLists/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/ContactImports/IContactsImportCollectionResource.cs

@@ -0,0 +1,29 @@
+namespace Mailtrap.ContactImports;
+
+/// <summary>
+/// Represents Contact imports collection resource.
+/// </summary>
+public interface IContactsImportCollectionResource : IRestResource
+{
+    /// <summary>
+    /// Import contacts in bulk with support for custom fields and list management.
+    /// Existing contacts with matching email addresses will be updated automatically.
+    /// You can import up to 50,000 contacts per request.
+    /// The import process runs asynchronously - use the returned
+    /// import ID to check the status and results.
+    /// List all contacts with details into <paramref name="request"/>.
+    /// </summary>
+    ///
+    /// <param name="request">
+    /// Request containing contact list for import.
+    /// </param>
+    ///
+    /// <param name="cancellationToken">
+    /// Token to control operation cancellation.
+    /// </param>
+    ///
+    /// <returns>
+    /// Contact import id and status.
+    /// </returns>
+    public Task<ContactsImport> Create(ContactsImportRequest request, CancellationToken cancellationToken = default);
+}

src/Mailtrap.Abstractions/ContactImports/IContactsImportResource.cs

@@ -0,0 +1,20 @@
+namespace Mailtrap.ContactImports;
+
+/// <summary>
+/// Represents Contact import resource.
+/// </summary>
+public interface IContactsImportResource : IRestResource
+{
+    /// <summary>
+    /// Gets details of the contact import, represented by the current resource instance.
+    /// </summary>
+    ///
+    /// <param name="cancellationToken">
+    /// Token to control operation cancellation.
+    /// </param>
+    ///
+    /// <returns>
+    /// Requested contact import details.
+    /// </returns>
+    public Task<ContactsImport> GetDetails(CancellationToken cancellationToken = default);
+}

src/Mailtrap.Abstractions/ContactImports/Models/ContactsImport.cs

@@ -0,0 +1,63 @@
+namespace Mailtrap.ContactImports.Models;
+
+/// <summary>
+/// Generic response object for contact imports operations.
+/// </summary>
+public record ContactsImport
+{
+    /// <summary>
+    /// Gets created contact imports identifier.
+    /// </summary>
+    ///
+    /// <value>
+    /// Contact imports identifier.
+    /// </value>
+    [JsonPropertyName("id")]
+    [JsonPropertyOrder(1)]
+    [JsonRequired]
+    public long Id { get; set; }
+
+    /// <summary>
+    /// Gets contact imports status.
+    /// </summary>
+    ///
+    /// <value>
+    /// Contact imports status.
+    /// </value>
+    [JsonPropertyName("status")]
+    [JsonPropertyOrder(2)]
+    public ContactsImportStatus Status { get; set; } = ContactsImportStatus.Unknown;
+
+    /// <summary>
+    /// Gets count of created contacts.
+    /// </summary>
+    ///
+    /// <value>
+    /// Count of created contacts.
+    /// </value>
+    [JsonPropertyName("created_contacts_count")]
+    [JsonPropertyOrder(3)]
+    public long? CreatedContactsCount { get; set; }
+
+    /// <summary>
+    /// Gets count of updated contacts.
+    /// </summary>
+    ///
+    /// <value>
+    /// Count of updated contacts.
+    /// </value>
+    [JsonPropertyName("updated_contacts_count")]
+    [JsonPropertyOrder(4)]
+    public long? UpdatedContactsCount { get; set; }
+
+    /// <summary>
+    /// Gets count of contacts over limit.
+    /// </summary>
+    ///
+    /// <value>
+    /// Count of contacts over limit.
+    /// </value>
+    [JsonPropertyName("contacts_over_limit_count")]
+    [JsonPropertyOrder(5)]
+    public long? ContactsOverLimitCount { get; set; }
+}