{"id":13431519,"url":"https://github.com/Jericho/CakeMail.RestClient","last_synced_at":"2025-03-16T11:31:53.936Z","repository":{"id":28169422,"uuid":"31670608","full_name":"Jericho/CakeMail.RestClient","owner":"Jericho","description":".NET wrapper for the CakeMail API","archived":true,"fork":false,"pushed_at":"2022-06-22T15:28:30.000Z","size":940,"stargazers_count":9,"open_issues_count":3,"forks_count":3,"subscribers_count":4,"default_branch":"develop","last_synced_at":"2025-01-19T23:39:20.205Z","etag":null,"topics":["cakemail","email"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Jericho.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-03-04T17:40:34.000Z","updated_at":"2024-08-05T22:18:33.000Z","dependencies_parsed_at":"2022-07-31T07:48:03.271Z","dependency_job_id":null,"html_url":"https://github.com/Jericho/CakeMail.RestClient","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jericho%2FCakeMail.RestClient","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jericho%2FCakeMail.RestClient/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jericho%2FCakeMail.RestClient/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jericho%2FCakeMail.RestClient/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Jericho","download_url":"https://codeload.github.com/Jericho/CakeMail.RestClient/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243863225,"owners_count":20360286,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cakemail","email"],"created_at":"2024-07-31T02:01:03.762Z","updated_at":"2025-03-16T11:31:51.063Z","avatar_url":"https://github.com/Jericho.png","language":"C#","funding_links":[],"categories":["Frameworks, Libraries and Tools","框架, 库和工具"],"sub_categories":["SDKs","开发工具包SDKs"],"readme":"# CakeMail.RestClient\n\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](http://jericho.mit-license.org/)\n[![Build status](https://ci.appveyor.com/api/projects/status/m8lsx7snrc5jdrdi?svg=true)](https://ci.appveyor.com/project/Jericho/cakemail-restclient)\n[![Coverage Status](https://coveralls.io/repos/Jericho/CakeMail.RestClient/badge.svg)](https://coveralls.io/r/Jericho/CakeMail.RestClient)\n[![CodeFactor](https://www.codefactor.io/repository/github/jericho/cakemail.restclient/badge)](https://www.codefactor.io/repository/github/jericho/cakemail.restclient)\n[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bhttps%3A%2F%2Fgithub.com%2FJericho%2FCakeMail.RestClient.svg?type=shield)](https://app.fossa.io/projects/git%2Bhttps%3A%2F%2Fgithub.com%2FJericho%2FCakeMail.RestClient?ref=badge_shield)\n\n## About\n\nCakeMail.RestClient is a C# client for the CakeMail service through its RESTful API.\n\n## Nuget\n\nCakeMailRestAPI is available as a Nuget package.\n\n[![NuGet Version](http://img.shields.io/nuget/v/CakeMail.RestClient.svg)](https://www.nuget.org/packages/CakeMail.RestClient/)\n\nPre-release packages are available on my MyGet feed:\n\n[![MyGet Pre Release](https://img.shields.io/myget/jericho/vpre/cakemail.restclient.svg)](http://myget.org/gallery/jericho)\n\n\n## Release Notes\n\n\n\n+ **7.1**\n    - Add support for dynamic content which CakeMail already supports when sending bulk emails. In other words, you can have `IF ... ELSEIF ... ELSE ... ENDIF` in your HTML content, text content and subject as well.\n    - Please keep in mind the following the rules established by CakeMail for dynamic content:\n      - `IF`, `ELSEIF`, `ELSE` and `ENDIF` must be upper case which means that ``[IF `myfield` = \"myValue\"]`` is valid but ``[if `myfield` = \"myValue\"]`` is not.\n      - square bracket is the delimeter which means that ``[IF `myfield` = \"myValue\"]`` is valid but ``{IF `myfield` = \"myValue\"}`` is not.\n      - the name of the data field must be surrounded by back ticks (not to be confused with single quotes) which means that ``[IF `firstname` = \"Bob\"]`` is valid but ``[IF 'firstname' = \"Bob\"]`` is not.\n      - you can only compare a field to a constant value and you can't compare a field to another field which means that ``[IF `firstname` = \"Bob\"]`` is valid but ``[IF `firstname` = `nickname`]`` is not.\n      - the constant value must be surrounded with double quotes when it's a string which means that ``[IF `firstname` = \"Bob\"]`` is valid but ``[IF `firstname` = 'Bob']`` is not.\n      - the constant value must not be surrounded by any quotes when it's a numeric value which means that ``[IF `age` \u003e= 18]`` is valid.\n      - the data field must be on the left side of the comparison which means that ``[IF `gender` = \\\"Male\\\"]`` is valid but ``[IF \\\"Male\\\" = `gender`]`` is not.\n      - you can have multiple conditions seperated by `AND` or `OR` which means that ``IF `firstname` = \"Bob\" AND `lastname` = \"Smith\"]`` is valid.\n      - the acceptable operators when comparing a field to a string value: `\u003c`, `\u003c=`, `=`, `!=`, `\u003e=`, `\u003e`, `LIKE` and `NOT LIKE`\n      - the acceptable operators when comparing a field to a mumeric value: `\u003c`, `\u003c=`, `=`, `!=`, `\u003e=` and `\u003e`\n```csharp\nvar subject = \"Special sale ends today\";\nvar html = \"\u003chtml\u003e\u003cbody\u003e[IF `gender` = \\\"Male\\\"]Men's clothing is on sale[ELSE]Women's clothing is on sale[ENDIF]\u003c/body\u003e\u003c/html\u003e\";\nvar text = \"[IF `gender` = \\\"Male\\\"]Men's clothing is on sale[ELSE]Women's clothing is on sale[ENDIF]\";\nvar mergeData = new Dictionary\u003cstring, object\u003e\n{\n    { \"gender\", \"Male\" }\n};\nvar sent = await client.Relays.SendWithoutTrackingAsync(userKey, \"recipient@example.com\", subject, html, text, \"you@yourcompany.com\", \"Your name\", mergeData, null, null, clientId, cancellationToken).ConfigureAwait(false);\n```\n\n+ **7.0**\n    - Add support for merge fields in html, text content and subject line when sending an email. CakeMail already supports merge fields when sending bulk emails.\n    - Please keep in mind the following the rules for merge fields:\n      - square bracket is the delimeter which means that `[firstname]` is valid but `{firstname}` is not.\n      - you can specify a default value (sometimes called \"fallback value\") by adding a comma after the field name followed by the desired value. This default value is used when the value for the data field is undefined. For example: `Dear [firstname, friend]` will result in `Dear friend` if the firstname field is omitted or contains a null value for the current recipient.\n      - you can use `[TODAY]` to print the current date. Please note that `[NOW]` and `[DATE]` are also acceptable.\n      - when the merge field contains a numeric value or a datetime or when you use the `[TODAY]` merge field, you can specify a format string by adding the pipe character after the field name followed by the desired format string like so: `[TODAY | MMM d yyyy]`.\n      - Documentation for [datetime format string](https://msdn.microsoft.com/en-us/library/8kb3ddd4(v=vs.110).aspx)\n      - Documentation for [numeric format string](https://msdn.microsoft.com/en-us/library/0c899ak8(v=vs.110).aspx)\n```csharp\nvar subject = \"Special sale ends today\";\nvar html = \"\u003chtml\u003e\u003cbody\u003eDear [firstname, friend], our annual sale ends \u003cb\u003etoday\u003c/b\u003e [TODAY | MMMM d].\u003c/body\u003e\u003c/html\u003e\";\nvar text = \"[salutation] [lastname], our annual sale ends \u003cb\u003etoday\u003c/b\u003e [TODAY | MMMM d].\";\nvar mergeData = new Dictionary\u003cstring, object\u003e\n{\n    { \"salutation\", \"Mr.\" },\n    { \"firstname\", \"Bob\" },\n    { \"lastname\", \"Smith\" }\n};\nvar sent = await client.Relays.SendWithoutTrackingAsync(userKey, \"recipient@example.com\", subject, html, text, \"you@yourcompany.com\", \"Your name\", mergeData, null, null, clientId, cancellationToken).ConfigureAwait(false);\n```\n\n+ **6.0**\n    - Fix bug when retrieving a Client record and the 'last_activity' field contains empty date\n    - Add support for .NET STANDARD 1.3\n    - Replace RestSharp with PathosChild.Http.FluentClient \n    - Switch unit testing to xUnit\n    - Implement GitFlow and repeatable build process\n\n+ **5.0**\n    - Upgraded to .NET 4.5.2\n\n+ **4.0**\n    - All methods are now async.\n    - You can pass a cancellation token when invoking an async method.\n\nThis means, for example, that the following v3.0 call:\n\n```csharp\nvar count = cakeMail.Campaigns.GetCount(userKey, MailingStatus.Ongoing);\n```\n\nHas been replaced with the following v4.0 call :\n\n```csharp\nvar count = await cakeMail.Campaigns.GetCountAsync(userKey, MailingStatus.Ongoing);\n```\n\n+ **3.0**\n    - Methods are now logically grouped in separate resources. For instance, all methods related to users are grouped in a resource called 'Users', all methods related to campaigns are grouped in a resource called 'Campaigns', and so on.\n    - Methods have been renamed to avoid repetition. For example, GetCampaignsCount has been renamed GetCount off of the new 'Campaigns' resource.\n\nThis means, for example, that the following v2.0 call:\n\n```csharp\nvar count = cakeMail.GetCampaignsCount(userKey, MailingStatus.Ongoing);\n```\n\nHas been replaced with the following v3.0 call :\n\n```csharp\nvar count = cakeMail.Campaigns.GetCount(userKey, MailingStatus.Ongoing);\n```\n\n\n+ **2.0**\n    - Unique identifiers changed to 'long' instead of 'int'.\n    - \"Magic strings\" replaced with enums. For example, instead of specifying sort direction with 'asc' and 'desc', you can now use SortDirection.Ascending and SortDirection.Descending.\n    - Fix bug in CreateTemplateCategory which prevents creating new categories\n    - Fix bug in DeleteTemplateCategory which causes an exception to be thrown despite the fact the category was successfuly deleted\n    - Fix bug in GetListMembers which causes exception: 'Json does not contain property members'\n    - Fix GetTriggerLinksLogs\n    - Added XML comments file for convenient intellisense in Visual Studio\n\n+ **1.0**\n    - Initial release\n\n## Installation\n\nThe easiest way to include CakeMail.RestClient in your C# project is by grabing the nuget package:\n\n```\nPM\u003e Install-Package CakeMail.RestClient\n```\n\nOnce you have the CakeMail.RestClient library properly referenced in your project, add the following namespace:\n\n```csharp\nusing CakeMail.RestClient;\n```\n\n## Usage\n\n### Login\n\n```csharp\nvar apiKey = \"... your api key ...\";\nvar userName = \"youremail@whatever.com\";\nvar password = \"yourpassword\";\n\nvar cakeMail = new CakeMailRestClient(apiKey);\n\nvar loginInfo = await cakeMail.Users.LoginAsync(userName, password);\nvar userKey = loginInfo.UserKey;\n```\n\nQuick note regarding the user key: this value is valid for several days (I don't know exactly how long though) and therefore can be cached for a reasonable period of time. There is no need to repeatedly invoke the 'Login' method to get this value.\n\n### Campaigns\n\nA campaign is simply a way to logically group mailings toghether. You can think of campaigns as 'folders'. In fact, the CakeMail UI has a \"Manage folders\" button under the \"Campaigns\" tab where you will see all the campaigns.\nA word of caution: the word 'Campaign' is used in the CakeMail UI to refer to mailings which is really confusing!\n\n```csharp\nvar campaigns = await cakeMail.Campaigns.GetCampaignsAsync(userKey, status: MailingStatus.Ongoing, sortBy: MailingSortBy.Name, sortDirection: SortDirection.Ascending, limit: 50, offset: 0);\nvar campaignsCount = await cakeMail.Campaigns.GetCountAsync(userKey, MailingStatus.Ongoing);\n\nvar campaignId = await cakeMail.Campaigns.CreateAsync(userKey, \"2015 User Conference\");\nvar campaign = await cakeMail.Campaigns.GetAsync(userKey, campaignId);\nvar deleted = await cakeMail.Campaigns.DeleteAsync(userKey, campaignId);\n\n```\n\n### Lists\n\nA List is a collection of subscribers (or List Members, or Records). Each subscriber or List Member is uniquely identified by their email address, and may include an limited amount of Fields containing demographic information associated to each email address.\n\n```csharp\n\nvar lists = await cakeMail.Lists.GetListsAsync(userKey, sortBy: ListSortBy.Name, sortDirection: SortDirection.Descending, limit: 50, offset: 0);\nvar listsCount = await cakeMail.Lists.GetCountAsync(userKey);\n\nvar listId = await cakeMail.Lists.CreateAsync(userKey, \"Customers and Prospects\", \"The XYZ Marketing Group\", \"marketing@yourcompany.com\", true);\nawait cakeMail.Lists.AddFieldAsync(userKey, listId, \"first_name\", \"text\");\nawait cakeMail.Lists.AddFieldAsync(userKey, listId, \"last_name\", \"text\");\nawait cakeMail.Lists.AddFieldAsync(userKey, listId, \"customer_since\", \"datetime\");\n```\n\nYou can add members to your list like so:\n\n```csharp\n\nawait cakeMail.Lists.SubscribeAsync(userKey, listId, \"bob_the_customer@hotmail.com\", true, true, new[]\n{\n    new KeyValuePair\u003cstring, object\u003e(\"first_name\", \"Bob\"), \n    new KeyValuePair\u003cstring, object\u003e(\"last_name\", \"Smith\"), \n    new KeyValuePair\u003cstring, object\u003e(\"customer_since\", DateTime.UtcNow) \n});\nawait cakeMail.Lists.SubscribeAsync(userKey, listId, \"jane_the_prospect@hotmail.com\", true, true, new[]\n{\n    new KeyValuePair\u003cstring, object\u003e(\"first_name\", \"Jane\"), \n    new KeyValuePair\u003cstring, object\u003e(\"last_name\", \"Doe\")\n});\n```\n\nor you can import a group of members:\n\n```csharp\nvar member1 = new ListMember()\n{\n    Email = \"bob_the_customer@hotmail.com\",\n    CustomFields = new Dictionary\u003cstring, object\u003e()\n    {\n        { \"first_name\", \"Bob\" },\n        { \"last_name\", \"Smith\" },\n        { \"customer_since\", DateTime.UtcNow }\n    }\n};\n\nvar member2 = new ListMember()\n{\n    Email = \"jane_the_prospect@hotmail.com\",\n    CustomFields = new Dictionary\u003cstring, object\u003e()\n    {\n        { \"first_name\", \"Jane\" },\n        { \"last_name\", \"Doe\" }\n    }\n};\n\nvar importResult = await cakeMail.Lists.ImportAsync(userKey, listId, new[] { member1, member2 });\n```\n\n### Mailings\n\nA mailing is an email campaign. It can be used to send standard email campaigns, A/B split campaigns or recurring campaigns.\n\n```csharp\nvar invitationMailingId = await cakeMail.Mailings.CreateAsync(userKey, \"2015 User Conference invitation\", campaignId);\nawait cakeMail.Mailings.UpdateAsync(userKey, invitationMailingId, listId: listId, htmlContent: \"\u003chtml\u003e\u003cbody\u003eYou are invited to attend our annual user conference\u003c/body\u003e\u003c/html\u003e\", textContent: \"You are invited to attend our annual user conference\", subject: \"Invitation to our 2015 user conference\");\nawait cakeMail.Mailings.SheduleAsync(userKey, invitationMailingId);\n\nvar reminderMailingId = await cakeMail.Mailings.CreateAsync(userKey, \"2015 User Conference reminder\", campaignId);\nawait cakeMail.Mailings.UpdateAsync(userKey, reminderMailingId, listId: listId, htmlContent: \"\u003chtml\u003e\u003cbody\u003eDon't forget our upcoming annual user conference\u003c/body\u003e\u003c/html\u003e\", textContent: \"Don't forget our upcoming annual user conference\", subject: \"Reminder about our 2015 user conference\");\nawait cakeMail.Mailings.SheduleAsync(userKey, reminderMailingId, DateTime.UtcNow.AddDays(2));\n```\n\n\n## License\n[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bhttps%3A%2F%2Fgithub.com%2FJericho%2FCakeMail.RestClient.svg?type=large)](https://app.fossa.io/projects/git%2Bhttps%3A%2F%2Fgithub.com%2FJericho%2FCakeMail.RestClient?ref=badge_large)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJericho%2FCakeMail.RestClient","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FJericho%2FCakeMail.RestClient","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJericho%2FCakeMail.RestClient/lists"}