Our API is released with stability in mind for folks to build around our service. We improve and introduce new usable methods regularly.
\nIf you find something odd, think something's missing, or want to make a feature request, leave a note.
\nAll of our API requests look for a Bearer token. Organization administrators can generate API keys at any time.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"39607124","collectionId":"b188d139-a966-4327-96e6-e2c968c284aa","publishedId":"2sAYdfpqTW","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2025-09-29T16:56:16.000Z"},"item":[{"name":"Agents (Coming Soon)","item":[{"name":"Activate agent","event":[{"id":"067d72d0-cb13-48aa-9460-543ec1874c60","listen":"test","script":{"id":"53d2f832-9a72-479d-b22e-df181f93efbb","exec":["pm.test(\"Status code is 2xx or 404\", function () {"," const code = pm.response.code;"," pm.expect("," code,"," `Expected status 2xx or 404 but got ${code}`"," ).to.satisfy((c) => (c >= 200 && c < 300) || c === 404);","});",""],"type":"text/javascript","packages":{},"requests":{}}}],"id":"7c3719e8-35de-4bc5-b91c-5716b2196a10","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n \"api\": true\r\n}\r\n","options":{"raw":{"language":"json"}}},"url":"https://{{serverPrefix}}.api.tryletterhead.com/api/v3/agents//actions/activate","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{apiKey}}"}]},"isInherited":true,"source":{"_postman_id":"b188d139-a966-4327-96e6-e2c968c284aa","id":"b188d139-a966-4327-96e6-e2c968c284aa","name":"Letterhead API","type":"collection"}},"urlObject":{"protocol":"https","path":["api","v3","agents","","actions","activate"],"host":["{{serverPrefix}}","api","tryletterhead","com"],"query":[{"disabled":true,"key":"","value":""}],"variable":[]}},"response":[],"_postman_id":"7c3719e8-35de-4bc5-b91c-5716b2196a10"},{"name":"Create agent","event":[{"listen":"test","script":{"id":"38b0b037-9e48-4749-9c31-8412655ac5f2","exec":["pm.test(\"Status code is 2xx or 409\", function () {"," const code = pm.response.code;"," pm.expect("," (code >= 200 && code < 300) || code === 409,"," `expected status 2xx or 409 but found ${code}`"," ).to.be.true;","});",""],"type":"text/javascript","packages":{},"requests":{}}}],"id":"98f52bf2-ae7d-4f86-9a20-1277a7b48f24","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[{"key":"api","value":"true","type":"text","uuid":"6c48b618-a9a9-400d-bca8-a8e8101a1331"},{"key":"type","value":"0","type":"text","uuid":"b6fa1654-3f8a-48f4-b3f1-499cdef42d2b"}]},"url":"https://{{serverPrefix}}.api.tryletterhead.com/api/v3/agents","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{apiKey}}"}]},"isInherited":true,"source":{"_postman_id":"b188d139-a966-4327-96e6-e2c968c284aa","id":"b188d139-a966-4327-96e6-e2c968c284aa","name":"Letterhead API","type":"collection"}},"urlObject":{"protocol":"https","path":["api","v3","agents"],"host":["{{serverPrefix}}","api","tryletterhead","com"],"query":[],"variable":[]}},"response":[{"id":"c842125b-99a4-4072-a2f5-1277913bb0be","name":"Create agent","originalRequest":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[{"key":"api","value":"true","type":"text","uuid":"6c48b618-a9a9-400d-bca8-a8e8101a1331"},{"key":"type","value":"0","type":"text","uuid":"b6fa1654-3f8a-48f4-b3f1-499cdef42d2b"}]},"url":"https://{{serverPrefix}}.api.tryletterhead.com/api/v3/agents"},"status":"Conflict","code":409,"_postman_previewlanguage":null,"header":[{"key":":status","value":409},{"key":"server","value":"nginx/1.27.3"},{"key":"content-type","value":"application/json"},{"key":"x-powered-by","value":"PHP/7.4.33"},{"key":"access-control-allow-origin","value":"*"},{"key":"access-control-allow-credentials","value":"true"},{"key":"access-control-max-age","value":"86400"},{"key":"cache-control","value":"no-cache, private"},{"key":"date","value":"Thu, 26 Mar 2026 16:07:49 GMT"},{"key":"via","value":"1.1 google"},{"key":"alt-svc","value":"h3=\":443\"; ma=2592000"}],"cookie":[],"responseTime":null,"body":"{\n \"data\": [],\n \"items\": [],\n \"message\": \"Cannot create an all-channels agent when channel-specific agents of this type exist.\",\n \"total\": 0\n}"}],"_postman_id":"98f52bf2-ae7d-4f86-9a20-1277a7b48f24"},{"name":"Deactivate agent","event":[{"id":"cdb75eef-44bf-411a-857f-ded3fe71c3e2","listen":"test","script":{"id":"84815e89-8e94-40a3-94e6-136e44f44386","exec":[""],"type":"text/javascript","packages":{},"requests":{}}}],"id":"200ab85f-6a92-43c6-941a-f2304abb27a9","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n \"api\": true\r\n}\r\n","options":{"raw":{"language":"json"}}},"url":"https://{{serverPrefix}}.api.tryletterhead.com/api/v3/agents//actions/deactivate","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{apiKey}}"}]},"isInherited":true,"source":{"_postman_id":"b188d139-a966-4327-96e6-e2c968c284aa","id":"b188d139-a966-4327-96e6-e2c968c284aa","name":"Letterhead API","type":"collection"}},"urlObject":{"protocol":"https","path":["api","v3","agents","","actions","deactivate"],"host":["{{serverPrefix}}","api","tryletterhead","com"],"query":[{"disabled":true,"key":"","value":""}],"variable":[]}},"response":[],"_postman_id":"200ab85f-6a92-43c6-941a-f2304abb27a9"},{"name":"Delete agent","event":[{"id":"0c196e44-46ce-4486-9a01-a92dd86e5c8f","listen":"test","script":{"id":"16a8cf6c-b3d6-4402-ad2c-253c0b84d36f","exec":[""],"type":"text/javascript","packages":{},"requests":{}}}],"id":"66c22cd5-9532-4b78-a828-31090335efc8","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"DELETE","header":[],"body":{"mode":"raw","raw":"{\r\n \"api\": true\r\n}\r\n","options":{"raw":{"language":"json"}}},"url":"https://{{serverPrefix}}.api.tryletterhead.com/api/v3/agents/agentUuid","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{apiKey}}"}]},"isInherited":true,"source":{"_postman_id":"b188d139-a966-4327-96e6-e2c968c284aa","id":"b188d139-a966-4327-96e6-e2c968c284aa","name":"Letterhead API","type":"collection"}},"urlObject":{"protocol":"https","path":["api","v3","agents","agentUuid"],"host":["{{serverPrefix}}","api","tryletterhead","com"],"query":[{"disabled":true,"key":"","value":""}],"variable":[]}},"response":[],"_postman_id":"66c22cd5-9532-4b78-a828-31090335efc8"},{"name":"Get agent","event":[{"id":"13908f09-663c-49d8-8dfc-7eee1efc02ee","listen":"test","script":{"type":"text/javascript","exec":["pm.test(\"Status code is 2xx or 404\", function () {"," pm.expect((pm.response.code >= 200 && pm.response.code < 300) || pm.response.code === 404).to.be.true;","});"]}}],"id":"49eb8735-bdc2-4691-8cb0-24f8ea0c2efe","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://{{serverPrefix}}.api.tryletterhead.com/api/v3/agents/?api=true","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{apiKey}}"}]},"isInherited":true,"source":{"_postman_id":"b188d139-a966-4327-96e6-e2c968c284aa","id":"b188d139-a966-4327-96e6-e2c968c284aa","name":"Letterhead API","type":"collection"}},"urlObject":{"protocol":"https","path":["api","v3","agents",""],"host":["{{serverPrefix}}","api","tryletterhead","com"],"query":[{"key":"api","value":"true"}],"variable":[]}},"response":[],"_postman_id":"49eb8735-bdc2-4691-8cb0-24f8ea0c2efe"},{"name":"List all agents","event":[{"id":"fb60768d-93bb-4674-a94a-8bb998536dc2","listen":"test","script":{"id":"7b0aca43-ec23-44ff-802a-37884e3c8e72","exec":["pm.test(\"Status code is 2xx\", function () {"," pm.response.to.be.success;","});",""],"type":"text/javascript","packages":{},"requests":{}}}],"id":"3600fdae-e71b-43ac-b40c-b1caed9e008e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://{{serverPrefix}}.api.tryletterhead.com/api/v3/agents?api=true","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{apiKey}}"}]},"isInherited":true,"source":{"_postman_id":"b188d139-a966-4327-96e6-e2c968c284aa","id":"b188d139-a966-4327-96e6-e2c968c284aa","name":"Letterhead API","type":"collection"}},"urlObject":{"protocol":"https","path":["api","v3","agents"],"host":["{{serverPrefix}}","api","tryletterhead","com"],"query":[{"key":"api","value":"true"}],"variable":[]}},"response":[],"_postman_id":"3600fdae-e71b-43ac-b40c-b1caed9e008e"},{"name":"Update agent","event":[{"id":"4dc22f2c-ad9c-488b-b39b-331a9572f5d9","listen":"test","script":{"id":"cc0ae2d2-6c1c-4f78-a73c-c46bbdfd5ee3","exec":["pm.test(\"Status code is 2xx\", function () {"," pm.response.to.be.success;","});",""],"type":"text/javascript","packages":{},"requests":{}}}],"id":"154ce1d7-772d-457d-b1d4-6badf7409f2a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n \"api\": true,\r\n \"name\": \"Updated Agent Name\",\r\n \"guidelines\": \"New instructions for the AI.\",\r\n \"runMode\": 1,\r\n \"channels\": [\r\n {{channel}}\r\n ]\r\n}\r\n","options":{"raw":{"language":"json"}}},"url":"https://{{serverPrefix}}.api.tryletterhead.com/api/v3/agents/","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{apiKey}}"}]},"isInherited":true,"source":{"_postman_id":"b188d139-a966-4327-96e6-e2c968c284aa","id":"b188d139-a966-4327-96e6-e2c968c284aa","name":"Letterhead API","type":"collection"}},"urlObject":{"protocol":"https","path":["api","v3","agents",""],"host":["{{serverPrefix}}","api","tryletterhead","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"154ce1d7-772d-457d-b1d4-6badf7409f2a"}],"id":"ad77a65a-99eb-4a2e-8fd2-a244f98043e7","event":[{"listen":"prerequest","script":{"id":"bbf39d6a-e520-44af-88a1-3f5e529015b7","type":"text/javascript","packages":{},"requests":{},"exec":[""]}},{"listen":"test","script":{"id":"0f8a1ac9-1c28-49fa-a944-af428c555c87","type":"text/javascript","requests":{},"exec":[""]}}],"_postman_id":"ad77a65a-99eb-4a2e-8fd2-a244f98043e7","description":"","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{apiKey}}"}]},"isInherited":true,"source":{"_postman_id":"b188d139-a966-4327-96e6-e2c968c284aa","id":"b188d139-a966-4327-96e6-e2c968c284aa","name":"Letterhead API","type":"collection"}}},{"name":"Audience","item":[{"name":"Create or Update Audience Member","id":"62908198-a987-48da-9591-8b887b50d0a8","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[{"key":"api","value":"true","description":"required | When set to true, this endpoint will accept authorization with your API Key.
required string[]| The slug or the unique identifier of a channel belonging to your organization.
required | The email address of your audience member.
\n","type":"text"},{"key":"channelSubscriberStatus ","value":"1","description":"required | The intended subscription status of your audience member.
\n","type":"text"},{"key":"welcome","value":"false","description":"When set to true, trigger a Welcome email when a new audience member is added. The \"Welcome\" automation must be configured in a given channel. Note that when true this will send regardless of the audience member's subscription status.
Create or update an audience member for a given organization. Our v3 API requires a company-level API key.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{apiKey}}"}]},"isInherited":true,"source":{"_postman_id":"b188d139-a966-4327-96e6-e2c968c284aa","id":"b188d139-a966-4327-96e6-e2c968c284aa","name":"Letterhead API","type":"collection"}},"urlObject":{"protocol":"https","path":["api","v3","audience"],"host":["{{serverPrefix}}","api","tryletterhead","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"62908198-a987-48da-9591-8b887b50d0a8"},{"name":"List Segments","event":[{"listen":"test","script":{"id":"1f2279a1-6b35-4dfc-bc37-cae99c0709e4","exec":["pm.test(\"Status code is 200\", function () {\r"," pm.response.to.have.status(200);\r","});"],"type":"text/javascript","packages":{},"requests":{}}}],"id":"01251bba-1d4a-4621-96d3-608271a74107","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://{{serverPrefix}}.api.tryletterhead.com/api/v3/audience/segments?api=true","description":"List your custom audience segments across all of your channels. At present, our API doesn't include dynamic segments that Letterhead provides. Our v3 API requires a company-level API key.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{apiKey}}"}]},"isInherited":true,"source":{"_postman_id":"b188d139-a966-4327-96e6-e2c968c284aa","id":"b188d139-a966-4327-96e6-e2c968c284aa","name":"Letterhead API","type":"collection"}},"urlObject":{"protocol":"https","path":["api","v3","audience","segments"],"host":["{{serverPrefix}}","api","tryletterhead","com"],"query":[{"key":"api","value":"true"}],"variable":[]}},"response":[{"id":"678cf7e5-2cdb-4af8-a7d7-7de9be01ee37","name":"List Segments","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://{{serverPrefix}}.api.tryletterhead.com/api/v3/audience/segments?api=true","protocol":"https","host":["{{serverPrefix}}","api","tryletterhead","com"],"path":["api","v3","audience","segments"],"query":[{"key":"api","value":"true"}]}},"status":"OK","code":200,"_postman_previewlanguage":null,"header":[{"key":"server","value":"nginx/1.27.3"},{"key":"content-type","value":"application/json"},{"key":"x-powered-by","value":"PHP/7.4.33"},{"key":"access-control-allow-origin","value":"*"},{"key":"access-control-allow-credentials","value":"true"},{"key":"access-control-max-age","value":"86400"},{"key":"cache-control","value":"no-cache, private"},{"key":"date","value":"Thu, 16 Apr 2026 19:04:43 GMT"},{"key":"via","value":"1.1 google"},{"key":"Alt-Svc","value":"h3=\":443\"; ma=2592000"},{"key":"Transfer-Encoding","value":"chunked"}],"cookie":[],"responseTime":null,"body":"{\n \"items\": [\n {\n \"uniqueId\": 1,\n \"channel\": \"black-bitter-coffee\",\n \"name\": \"Testaroo\",\n \"createdAt\": \"2025-07-24 01:28:39\",\n \"updatedAt\": \"2025-11-15 03:00:31\",\n \"criteria\": [\n {\n \"attribute\": \"tags\",\n \"category\": \"tags\",\n \"operator\": \"IN\",\n \"value\": [\n \"Staff\"\n ]\n },\n {\n \"attribute\": \"tags\",\n \"category\": \"tags\",\n \"operator\": \"IN\",\n \"value\": [\n \"Border-collies\"\n ]\n },\n {\n \"attribute\": \"age\",\n \"category\": \"commonFields\",\n \"operator\": \">\",\n \"value\": \"3\"\n }\n ],\n \"isOrBoolean\": false\n },\n ],\n \"message\": \"\",\n \"total\": 1\n}"}],"_postman_id":"01251bba-1d4a-4621-96d3-608271a74107"}],"id":"49bc0f32-593c-4c6d-91a8-c6ae32b7217f","_postman_id":"49bc0f32-593c-4c6d-91a8-c6ae32b7217f","description":"","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{apiKey}}"}]},"isInherited":true,"source":{"_postman_id":"b188d139-a966-4327-96e6-e2c968c284aa","id":"b188d139-a966-4327-96e6-e2c968c284aa","name":"Letterhead API","type":"collection"}}},{"name":"Automations","item":[{"name":"Change automation template","event":[{"listen":"test","script":{"id":"3ad8afd0-ce38-44f7-b5da-43f6192cb901","exec":["// ---- Change automation template: success response validations (200) ----","","pm.test(\"Response is JSON\", function () {"," pm.response.to.be.json;","});","","const json = pm.response.json();","","pm.test(\"Body has keys: items, message, total\", function () {"," pm.expect(json).to.be.an(\"object\");"," pm.expect(json).to.have.property(\"items\");"," pm.expect(json).to.have.property(\"message\");"," pm.expect(json).to.have.property(\"total\");","});","","pm.test(\"items is null\", function () {"," // For the 422 response, the API returns items as an array (often empty)"," pm.expect(pm.response.code).to.equal(422);"," pm.expect(json.items).to.be.an(\"array\");","});","","pm.test(\"total is number 0\", function () {"," pm.expect(json.total).to.be.a(\"number\");"," pm.expect(json.total).to.equal(0);","});","","pm.test(\"message is a string\", function () {"," pm.expect(json.message).to.be.a(\"string\");","});","","pm.test(\"If status is 200, message is exact success string\", function () {"," if (pm.response.code === 200) {"," pm.expect(json.message).to.equal(\"Automation template has been updated\");"," } else {"," // Not a failure for non-200 runs; this script is focused on the 200 example."," pm.expect(true).to.equal(true);"," }","});",""],"type":"text/javascript","packages":{},"requests":{}}}],"id":"4afb5bf1-c2eb-4fcf-9b0a-29c59050786f","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[{"key":"api","value":"true","description":"required | When set to true, this endpoint will accept authorization with your API Key.
required | string | The identifier of the template to set for the automation.
Using the v3 API, which requires a key generated from the company-level, this endpoint allows you to change the active template of an automation.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{apiKey}}"}]},"isInherited":true,"source":{"_postman_id":"b188d139-a966-4327-96e6-e2c968c284aa","id":"b188d139-a966-4327-96e6-e2c968c284aa","name":"Letterhead API","type":"collection"}},"urlObject":{"protocol":"https","path":["api","v3","automations","{{automationUniqueId}}","actions","change-template"],"host":["{{serverPrefix}}","api","tryletterhead","com"],"query":[],"variable":[]}},"response":[{"id":"e06c5a92-8f88-4ebb-b990-0ba687f55a61","name":"200 Success","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\"items\":null,\"message\":\"Automation template has been updated\",\"total\":0}","options":{"raw":{"language":"json"}}},"url":"https://{{serverPrefix}}.api.tryletterhead.com/api/v3/automations/{{automationUuid}}/actions/change-active-template"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","enabled":true}],"cookie":[],"responseTime":null,"body":"{\"items\":null,\"message\":\"Automation template has been updated\",\"total\":0}"},{"id":"856da0b3-77ad-4741-ab02-55f33de162e2","name":"400 Template not found","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\"items\":null,\"message\":\"Template with ID {templateId} not found.\",\"total\":0}","options":{"raw":{"language":"json"}}},"url":"https://{{serverPrefix}}.api.tryletterhead.com/api/v3/automations/{{automationUuid}}/actions/change-active-template"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","enabled":true}],"cookie":[],"responseTime":null,"body":"{\"items\":null,\"message\":\"Template with ID {templateId} not found.\",\"total\":0}"},{"id":"2dc5a2c1-b861-436d-9606-bddb2cd2259f","name":"404 Automation not found","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\"items\":null,\"message\":\"RecordNotFoundException — \\\"Automation with unique ID {uniqueId} not found.\\\"\",\"total\":0}","options":{"raw":{"language":"json"}}},"url":"https://{{serverPrefix}}.api.tryletterhead.com/api/v3/automations/{{automationUuid}}/actions/change-active-template"},"status":"Not Found","code":404,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","enabled":true}],"cookie":[],"responseTime":null,"body":"{\"items\":null,\"message\":\"RecordNotFoundException — \\\"Automation with unique ID {uniqueId} not found.\\\"\",\"total\":0}"},{"id":"e875ab25-f747-485c-bc9a-bf599925ba73","name":"422 Automation not in error state","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\"items\":null,\"message\":\"Cannot change template for automation {uniqueId}: automation is not in error state.\",\"total\":0}","options":{"raw":{"language":"json"}}},"url":"https://{{serverPrefix}}.api.tryletterhead.com/api/v3/automations/{{automationUuid}}/actions/change-active-template"},"status":"Unprocessable Entity (WebDAV) (RFC 4918)","code":422,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","enabled":true}],"cookie":[],"responseTime":null,"body":"{\"items\":null,\"message\":\"Cannot change template for automation {uniqueId}: automation is not in error state.\",\"total\":0}"},{"id":"fcdae63a-22f7-44ea-8a23-81e22741f231","name":"400 Template not active","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\"items\":null,\"message\":\"Template {templateId} is not active.\",\"total\":0}","options":{"raw":{"language":"json"}}},"url":"https://{{serverPrefix}}.api.tryletterhead.com/api/v3/automations/{{automationUuid}}/actions/change-active-template"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","enabled":true}],"cookie":[],"responseTime":null,"body":"{\"items\":null,\"message\":\"Template {templateId} is not active.\",\"total\":0}"}],"_postman_id":"4afb5bf1-c2eb-4fcf-9b0a-29c59050786f"},{"name":"Reactivate and Restart Automation","event":[{"id":"cce5658b-034e-42dc-a064-ef9f957b62da","listen":"test","script":{"id":"0d09a9c6-f22b-4345-8480-ef461d6354d3","exec":["// Prod smoke monitor tests for \"Reactivate and Restart Automation\"","// Goal: PASS only on 202. Explicitly FAIL on 404. Keep robust JSON / Content-Type assertions.","","pm.test(\"Status code is 202 (only passing status)\", function () {"," pm.expect(pm.response.code, `Expected 202 but got ${pm.response.code}`).to.eql(202);","});","","pm.test(\"Does not return 404\", function () {"," pm.expect(pm.response.code, \"404 indicates automation/template not found\").to.not.eql(404);","});","","pm.test(\"Content-Type is JSON\", function () {"," const ct = pm.response.headers.get(\"Content-Type\") || pm.response.headers.get(\"content-type\") || \"\";"," pm.expect(ct.toLowerCase()).to.include(\"application/json\");","});","","let json;","pm.test(\"Response body is valid JSON\", function () {"," pm.expect(function () { json = pm.response.json(); }).to.not.throw();"," pm.expect(json).to.be.an(\"object\");","});","","// Validate 202 response contract","pm.test(\"202 contract: keys message/items/total\", function () {"," pm.expect(pm.response.code).to.eql(202);",""," // Ensure json has been parsed even if previous test failed/was skipped"," if (!json) json = pm.response.json();",""," pm.expect(json).to.have.property(\"message\");"," pm.expect(json.message).to.be.a(\"string\").and.to.have.length.greaterThan(0);",""," pm.expect(json).to.have.property(\"items\");"," // In the 202 case, items may be null (no items to return) or an array"," pm.expect(json.items === null || Array.isArray(json.items), \"items should be null or an array\").to.eql(true);",""," pm.expect(json).to.have.property(\"total\");"," pm.expect(json.total).to.be.a(\"number\");",""," // Basic consistency check only when items is an array"," if (Array.isArray(json.items)) {"," pm.expect(json.total).to.eql(json.items.length);",""," // Ensure each item is an object (avoid overfitting to specific item fields)"," json.items.forEach((item) => pm.expect(item).to.be.an(\"object\"));"," }","});",""],"type":"text/javascript","packages":{},"requests":{}}}],"id":"ca06b3ca-7cec-4e8b-b8c7-31015a279543","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[{"key":"api","value":"true","description":"required | When set to true, this endpoint will accept authorization with your API Key.
This endpoint restarts the specified automation, in the event that as part of editorial -- someone didn't republish a change -- the automation disabled itself. Yep - this is a pretty specific use-case. The unpublished template will be published and then subsequently available to future automation use - and then the automation itself will be re-enabled.
\nOur v3 endpoints require a company-level API key.
Our Letters API -- api/v2/letters/... -- allows developers to interact with an organization's newsletters outside of the constraint of its Channel.
required | When true, instructs the endpoint that you're authenticating with an organization key as opposed to some other method. In almost all cases you will want to set this value to true.
required | string[] | An array of channel identifiers (or channel \"slugs\") across which to create a curation.
required | URL to the content you would like Letterhead to crawl. We will fetch what we can glean from the site's Open Graph.
\n","type":"text","uuid":"fdd27d16-d723-4846-a871-85f8334f16e3"},{"key":"author","value":"","description":"optional | The author of the piece of content.
\n","type":"text","uuid":"55d1a49b-3e04-40cb-aad1-ff811eb04af2"},{"key":"customFields[my-field]","value":"","description":"optional | string | Pass a custom field name and it's string value to store it with your curation. Note: Letterhead accepts only fields that are declared in your company curation settings. Other fields will be ignored. Custom fields are lowercase-and-sluggified. Example: \"Sponsor Name\" becomes sponsor-name.
optional | html content for the curation, only p and formatting elements are allowed. You would use this if
optional | Plain text excerpt of the curated content. Will overwrite what we fetch from the URL.
\n","type":"text","uuid":"ec40f2f7-c38d-48ba-9707-f8dd3ecad142"},{"key":"image","value":"","description":"optional | The URL of a featured image to associate with this piece of content.
\n","type":"text","uuid":"afdb67b3-fb9f-48d8-a732-d2856c6740d6"},{"key":"imageAlt","value":"","description":"optional | string[]
optional | string[]
optional | The name of the site the curated content originated from.
\n","type":"text","uuid":"485bf1f6-8aec-42e9-b90f-5c851c7e7ce8"},{"key":"publicationDate","value":"","description":"optional | The Y-md H:i:s formatted date of publication.
optional | string[] | An optional array of string tags with which to associate this piece of content. Example: ['dogs', 'canines']
optional | Title of the curated content. Will overwrite what we fetch from the URL.
\n","type":"text","uuid":"57b7338f-2e47-4cbf-8b84-67a0177e9062"}]},"url":"https://{{serverPrefix}}.api.tryletterhead.com/api/v3/curations","description":"Create a curation for any channel within the company. Note that the v3 api requires a key generated from within the company-level settings.
Provided that you are curating the same url, Letterhead will not create a duplicate curation, and you can use this endpoint to also update one if it is already in the system.
Create multiple curations for any channel within the company. Note that the v3 api requires a key generated from within the company-level settings.
Provided that you are curating the same url, Letterhead will not create a duplicate curation, and you can use this endpoint to also update one if it is already in the system.
It accepts the same parameters as the Curate endpoint.
required | When true, instructs the endpoint that you're authenticating with an organization key as opposed to some other method. In almost all cases you will want to set this value to true.
required | string[] | An array of channel identifiers (or channel \"slugs\") across which to create a curation.
required | The number of articles you want Letterhead to try to curate for you. Minimum 1, maximum 10.
\n","type":"text","uuid":"57b7338f-2e47-4cbf-8b84-67a0177e9062"},{"key":"subject","value":"Coffee Bean Growth","description":"required | The subject for Letterhead to search.
\n","type":"text","uuid":"f0414606-c95a-444f-9889-253be7bf93fc"}]},"url":"https://{{serverPrefix}}.api.tryletterhead.com/api/v3/curations/discover","description":"Given a subject, Letterhead will try to curate a number of relevant articles to the channels you instruct the API. We try to ensure they are relevant and recent, but please note this API is in beta, and we can't guarantee that these curations will always hit the mark.
Note that the v3 api requires a key generated from within the company-level settings, which are available only to Letterhead customers on a certain plan.
Version note: at present, you can only pass one channel identifier to channels. Shortly, you will able to pass multiple, or none - which will represent \"all channels.\"
required | When true, instructs the endpoint that you're authenticating with an organization key as opposed to some other method. In almost all cases you will want to set this value to true.
required | URL to the content you would like Letterhead to crawl. We will fetch what we can glean from the site's Open Graph.
\n","type":"text","uuid":"fdd27d16-d723-4846-a871-85f8334f16e3"},{"key":"channels[]","value":"letterhead-example-newsletter","description":"required | string[] | An array of channel identifiers (or channel \"slugs\") across which to create a curation.
optional | html content for the curation, only p and formatting elements are allowed. You would use this if
optional | Plain text excerpt of the curated content. Will overwrite what we fetch from the URL.
\n","type":"text","uuid":"ec40f2f7-c38d-48ba-9707-f8dd3ecad142"},{"key":"image","value":"","description":"optional | The URL of a featured image to associate with this piece of content.
\n","type":"text","uuid":"afdb67b3-fb9f-48d8-a732-d2856c6740d6"},{"key":"siteName","value":"","description":"optional | The name of the site the curated content originated from.
\n","type":"text","uuid":"485bf1f6-8aec-42e9-b90f-5c851c7e7ce8"},{"key":"publicationDate","value":"","description":"optional | The Y-md H:i:s formatted date of publication.
optional | string[] | An optional array of string tags with which to associate this piece of content. Example: ['dogs', 'canines']
optional | Title of the curated content. Will overwrite what we fetch from the URL.
\n","type":"text","uuid":"57b7338f-2e47-4cbf-8b84-67a0177e9062"}]},"url":"https://{{serverPrefix}}.api.tryletterhead.com/api/v3/curations","description":"Create a curation for any channel within the company. Note that the v3 api requires a key generated from within the company-level settings, which are available only to folks with that given plan.
Provided that you are curating the same url, Letterhead will not create a duplicate curation, and you can use this endpoint to also update one if it is already in the system.
Version note: at present, you can only pass one channel identifier to channels. Shortly, you will able to pass multiple, or none - which will represent \"all channels.\"
scrape is not presently an option, but will be added.
The v3 API is identical to the v2 API in almost every way other than scope. v3 endpoints accommodate company-wide management, and require keys generated from within a company's administrative settings.
required | When true, instructs the endpoint that you're authenticating with an organization key as opposed to some other method. In almost all cases you will want to set this value to true.
required | string[] | An array of channel identifiers (or channel \"slugs\") across which to create a curation.
required | URL to the content you would like Letterhead to crawl. We will fetch what we can glean from the site's Open Graph.
\n","type":"text","uuid":"fdd27d16-d723-4846-a871-85f8334f16e3"},{"key":"content","value":"","description":"optional | html content for the curation, only p and formatting elements are allowed. You would use this if
optional | Plain text excerpt of the curated content. Will overwrite what we fetch from the URL.
\n","type":"text","uuid":"ec40f2f7-c38d-48ba-9707-f8dd3ecad142"},{"key":"image","value":"","description":"optional | The URL of a featured image to associate with this piece of content.
\n","type":"text","uuid":"afdb67b3-fb9f-48d8-a732-d2856c6740d6"},{"key":"siteName","value":"","description":"optional | The name of the site the curated content originated from.
\n","type":"text","uuid":"485bf1f6-8aec-42e9-b90f-5c851c7e7ce8"},{"key":"publicationDate","value":"","description":"optional | The Y-md H:i:s formatted date of publication.
optional | string[] | An optional array of string tags with which to associate this piece of content. Example: ['dogs', 'canines']
optional | Title of the curated content. Will overwrite what we fetch from the URL.
\n","type":"text","uuid":"57b7338f-2e47-4cbf-8b84-67a0177e9062"}]},"url":"https://{{serverPrefix}}.api.tryletterhead.com/api/v2/curations","description":"Create a curation for any channel within an organization. Note that the v2 api requires a key generated from within the organization-level settings.
Provided that you are curating the same url, Letterhead will not create a duplicate curation, and you can use this endpoint to also update one if it is already in the system.
Version note: at present, you can only pass one channel identifier to channels. Shortly, you will able to pass multiple, or none - which will represent \"all channels.\"
scrape is not presently an option, but will be added.
The v2 API and the v3 API are almost identical except for scope. The v2 API accommodates organization-wide management, and requires keys generated from the organization level.
Curations allow companies to distribute content across one or more newsletters. While there are curation endpoints under the Channels namespace that allow users to manage a specific channel's content, this top-level endpoint allows for curations management across the entire company.
\n","_postman_id":"abbbf164-a65e-4074-8f74-e50dba1fb01b","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{apiKey}}"}]},"isInherited":true,"source":{"_postman_id":"b188d139-a966-4327-96e6-e2c968c284aa","id":"b188d139-a966-4327-96e6-e2c968c284aa","name":"Letterhead API","type":"collection"}}},{"name":"Channels","item":[{"name":"v3","item":[{"name":"Delete a channel","id":"8f43683e-6d1b-4ae9-8a05-0f493fcd63c3","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"DELETE","header":[],"body":{"mode":"formdata","formdata":[{"key":"api","value":"true","description":"required | When set to true, this endpoint will accept authorization with your API Key.
This API deletes a channel with the provided channel identifier. Note that v3 endpoints require company-wide level administrative keys, which prevents channel deletion on anything but the highest privileges.
The v3 API is identical to the v2 API in almost every way other than scope. v3 endpoints accommodate company-wide management, and require keys generated from within a company's administrative settings.
Your subscriber's subscription status is represented by a number (we know, not super intuitive ...). Our api will reject attempts to subscribe a person who has been unsubscribed or bounced.
\n","type":"text"},{"key":"customFields[custom-field-6]","value":"Custom field value","type":"text"},{"key":"email","value":"noodle@example.com","description":"The full, qualified email address of your new or existing subscriber. We use this to identify them: if we can't find a match, we'll add your person; otherwise, we'll update them - everything but the email itself.
\n","type":"text","contentType":""},{"key":"name","value":"Noodle the Pug II","description":"Your subscriber's name. You can pass an empty value, but you must pass the key.
\n","type":"text"},{"key":"welcome","value":"false","description":"Whether to trigger your \"Welcome letter.\" This takes effect only if you set the person's status to subscribed.
\n","type":"text"},{"key":"api","value":"false","description":"When true, instructs the endpoint that you're authenticating with an organization key as opposed to some other method. In almost all cases you will want to set this value to true.
Deprecation notice: this endpoint has been deprecated in favor of the top-level api/v2/audience endpoint, which allows developers to manage audience members across an entire organization. This endpoint will remain available, but its features will stay limited.
\nYou can add a new or update an existing subscriber with an email address - in a limited fashion. Right now, we only let you change their subscription status and name, but we will introduce new properties soon. Please let us know what you'd like to see.
\nNote: the /subscribers example below can be used as an alias to /audience . You may have seen references to such an endpoint. It still exists in v2, we just prefer to use a more general \"audience\" term to reflect people who might not technically be subscribers to a newsletter.
You can look up an existing audience member by their email address.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{apiKey}}"}]},"isInherited":true,"source":{"_postman_id":"b188d139-a966-4327-96e6-e2c968c284aa","id":"b188d139-a966-4327-96e6-e2c968c284aa","name":"Letterhead API","type":"collection"}},"urlObject":{"protocol":"https","path":["api","v2","channels","{{channel}}","audience",""],"host":["{{serverPrefix}}","api","tryletterhead","com"],"query":[{"description":{"content":"required | When true, instructs the endpoint that you're authenticating with an organization key as opposed to some other method. In almost all cases you will want to set this value to true.
optional | The number of records to return. Default is 10.
optional | The first name of the audience member.
\n","type":"text/plain"},"key":"name","value":null},{"description":{"content":"optional | integer | The page number for paginated results.
optional | integer | The newsletter subscription status of an audience member.
optional | The last name of the audience member.
\n","type":"text/plain"},"key":"surname","value":null},{"description":{"content":"optional | string[] | An array of tags matching audience members. This is an OR boolean search, so ['cats', 'dogs'] would be cats OR dogs.
Tag to create/update
\n","type":"text/plain"},"key":"tag","value":"string"},{"description":{"content":"User email address
\n","type":"text/plain"},"key":"email","value":"email"},{"description":{"content":"When true, instructs the endpoint that you're authenticating with an organization key as opposed to some other method. In almost all cases you will want to set this value to true.
Tag to create/update
\n","type":"text/plain"},"key":"tag","value":"string"},{"description":{"content":"User email address
\n","type":"text/plain"},"key":"email","value":"email"},{"description":{"content":"When true, instructs the endpoint that you're authenticating with an organization key as opposed to some other method. In almost all cases you will want to set this value to true.
We encourage you to manage your relationship with your channel's subscribers, and for folks who want to build around or integrate with other services, we try to give you both helpful and safe ways to go about it.
\n","_postman_id":"37261061-f9b0-4a85-b716-d3dcac0d5241","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{apiKey}}"}]},"isInherited":true,"source":{"_postman_id":"b188d139-a966-4327-96e6-e2c968c284aa","id":"b188d139-a966-4327-96e6-e2c968c284aa","name":"Letterhead API","type":"collection"}}},{"name":"Curations","item":[{"name":"Add curation","id":"efaca25b-895e-406b-809b-51e411b0bd10","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[{"key":"api","value":"true","description":"required | When true, instructs the endpoint that you're authenticating with an organization key as opposed to some other method. In almost all cases you will want to set this value to true.
required | URL to the content you would like Letterhead to crawl. We will fetch what we can glean from the site's Open Graph.
\n","type":"text"},{"key":"content","value":"","description":"optional | html content for the curation, only p and formatting elements are allowed. You would use this if
optional | Plain text excerpt of the curated content. Will overwrite what we fetch from the URL.
\n","type":"text"},{"key":"image","value":"","description":"optional | The URL of a featured image to associate with this piece of content.
\n","type":"text"},{"key":"siteName","value":"Black Bitter Coffee","description":"optional | The name of the site the curated content originated from.
\n","type":"text","uuid":"e0a526e9-d548-4988-ac92-10b4425642b0"},{"key":"publicationDate","value":"","description":"optional | The Y-md H:i:s formatted date of publication.
optional | string[] | An optional array of string tags with which to associate this piece of content. Example: ['dogs', 'canines']
optional | Title of the curated content. Will overwrite what we fetch from the URL.
\n","type":"text"},{"key":"crawl","value":"","description":"optional | When false, this disables the initial crawl of the content from the URL parameter.
optional | When false, this disables the initial crawl of the content from the URL parameter. An alias of the crawl parameter.
required | When true, instructs the endpoint that you're authenticating with an organization key as opposed to some other method. In almost all cases you will want to set this value to true.
required | URL to the content you would like Letterhead to crawl. We will fetch what we can glean from the site's Open Graph.
\n","type":"text"},{"key":"content","value":"I have been curated.
","description":"optional | html content for the curation, only p and formatting elements are allowed.
optional | Plain text excerpt of the curated content. Will overwrite what we fetch from the URL.
\n","type":"text"},{"key":"image","value":"https://letterhead.ai/hubfs/Letterhead_CTA9_July2023/images/footer_logo.svg","description":"optional | The URL of a featured image to associate with this piece of content.
\n","type":"text"},{"key":"publicationDate","value":"2024-02-05 00:00:00","description":"optional | The Y-m-d H:i:s formatted date of publication.
optional | The name of the site the curated content originated from.
\n","type":"text","uuid":"e3ad6c2b-4e02-4320-a959-463450e8b61d"},{"key":"tags[]","value":"delightfully-caffeinated","description":"optional | string[] | An optional array of string tags with which to associate this piece of content. Example: ['dogs', 'canines']
optional | Title of the curated content.
\n","type":"text"}]},"url":"https://{{serverPrefix}}.api.tryletterhead.com/api/v2/channels/{{channel}}/aggregates/{{curationUuid}}","description":"This endpoint allows you to update a curation for a specific channel.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{apiKey}}"}]},"isInherited":true,"source":{"_postman_id":"b188d139-a966-4327-96e6-e2c968c284aa","id":"b188d139-a966-4327-96e6-e2c968c284aa","name":"Letterhead API","type":"collection"}},"urlObject":{"protocol":"https","path":["api","v2","channels","{{channel}}","aggregates","{{curationUuid}}"],"host":["{{serverPrefix}}","api","tryletterhead","com"],"query":[],"variable":[]}},"response":[{"id":"21dedeae-6526-4522-a8eb-f91a42f8af81","name":"Update curation","originalRequest":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[{"key":"api","value":"true","description":"**required** | When `true`, instructs the endpoint that you're authenticating with an organization key as opposed to some other method. In almost all cases you will want to set this value to `true`. ","type":"text"},{"key":"url","value":"https://example.org","description":"**required** | URL to the content you would like Letterhead to crawl. We will fetch what we can glean from the site's Open Graph. ","type":"text"},{"key":"content","value":"I have been curated.
","description":"**optional** | `html` content for the curation, only `p` and formatting elements are allowed.","type":"text"},{"key":"excerpt","value":"The excerpt is often mapped with an RSS feed's description node - but not always.","description":"**optional** | Plain text excerpt of the curated content. Will overwrite what we fetch from the URL.","type":"text"},{"key":"image","value":"https://letterhead.ai/hubfs/Letterhead_CTA9_July2023/images/footer_logo.svg","description":"**optional** | The URL of a featured image to associate with this piece of content.","type":"text"},{"key":"publicationDate","value":"2024-02-05 00:00:00","description":"**optional** | The `Y-m-d H:i:s` formatted date of publication.","type":"text"},{"key":"siteName","value":"Black Bitter Coffee","description":"**optional** | The name of the site the curated content originated from.","type":"text","uuid":"e3ad6c2b-4e02-4320-a959-463450e8b61d"},{"key":"tags[]","value":"delightfully-caffeinated","description":"**optional** | `string[]` | An optional array of `string` tags with which to associate this piece of content. Example: `['dogs', 'canines']`","type":"text"},{"key":"title","value":"Is this the tastiest coffee ever?","description":"**optional** | Title of the curated content.","type":"text"}]},"url":"https://{{serverPrefix}}.tryletterhead.com/api/v2/channels/{{channel}}/aggregates/{{curationUuid}}"},"status":"Accepted","code":202,"_postman_previewlanguage":"json","header":[{"key":"Server","value":"nginx/1.14.0 (Ubuntu)"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Credentials","value":"true"},{"key":"Access-Control-Max-Age","value":"86400"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Date","value":"Wed, 05 Feb 2025 16:51:20 GMT"}],"cookie":[],"responseTime":null,"body":"{\n \"items\": {\n \"archived\": false,\n \"content\": \"I have been curated.
\",\n \"createdAt\": \"2025-01-07 00:01:12\",\n \"curated\": false,\n \"dateOfAggregatePublication\": \"2025-02-05 16:51:20\",\n \"excerpt\": \"The excerpt is often mapped with an RSS feed's description node - but not always.\",\n \"feedUniqueId\": \"\",\n \"image\": \"https://letterhead.ai/hubfs/Letterhead_CTA9_July2023/images/footer_logo.svg\",\n \"originalUrl\": \"https://css-tricks.com/how-to-make-a-folder-slit-effect-with-css/\",\n \"publicationDate\": \"2024-02-05 00:00:00\",\n \"siteName\": \"Black Bitter Coffee\",\n \"title\": \"Is this the tastiest coffee ever?\",\n \"uniqueId\": \"b8ee3a270d8615d23bf17335b2986bc3\",\n \"updatedAt\": \"2025-01-07 00:01:12\",\n \"tags\": [\n \"delightfully-caffeinated\"\n ]\n },\n \"message\": \"Your curation was successfully updated.\",\n \"total\": 1\n}"}],"_postman_id":"88248c65-a7b3-44f5-a79b-bb1ba2b2931b"}],"id":"a68b3a02-58c7-47c0-a6eb-dfc503e15a5f","description":"Letterhead makes it a little easier for publishers to make content by letting you curate pages from around the web.
\n","_postman_id":"a68b3a02-58c7-47c0-a6eb-dfc503e15a5f","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{apiKey}}"}]},"isInherited":true,"source":{"_postman_id":"b188d139-a966-4327-96e6-e2c968c284aa","id":"b188d139-a966-4327-96e6-e2c968c284aa","name":"Letterhead API","type":"collection"}}},{"name":"Letters","item":[{"name":"Metrics","item":[{"name":"Click metrics","id":"3b61e167-a0b6-4d76-96ef-f7c136118765","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://{{serverPrefix}}.api.tryletterhead.com/api/v2/channels/{{channel}}/letters/{{letterUuid}}/metrics/clicks?api=false","description":"View the click metrics of a published letter, given its UUID. For each URL that has been clicked at lease once, we'll return totals and uniques. These metrics aren't real time, and they will update periodically throughout the day.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{apiKey}}"}]},"isInherited":true,"source":{"_postman_id":"b188d139-a966-4327-96e6-e2c968c284aa","id":"b188d139-a966-4327-96e6-e2c968c284aa","name":"Letterhead API","type":"collection"}},"urlObject":{"protocol":"https","path":["api","v2","channels","{{channel}}","letters","{{letterUuid}}","metrics","clicks"],"host":["{{serverPrefix}}","api","tryletterhead","com"],"query":[{"description":{"content":"When true, instructs the endpoint that you're authenticating with an organization key as opposed to some other method. In almost all cases you will want to set this value to true. When false, you must provide a one-time use token.
List or search through newsletters based on their publication status or keywords.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{apiKey}}"}]},"isInherited":true,"source":{"_postman_id":"b188d139-a966-4327-96e6-e2c968c284aa","id":"b188d139-a966-4327-96e6-e2c968c284aa","name":"Letterhead API","type":"collection"}},"urlObject":{"protocol":"https","path":["api","v2","channels","{{channel}}","letters","1234"],"host":["{{serverPrefix}}","api","tryletterhead","com"],"query":[{"description":{"content":"When true, instructs the endpoint that you're authenticating with an organization key as opposed to some other method. In almost all cases you will want to set this value to true.
List or search through newsletters based on their publication status or keywords.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{apiKey}}"}]},"isInherited":true,"source":{"_postman_id":"b188d139-a966-4327-96e6-e2c968c284aa","id":"b188d139-a966-4327-96e6-e2c968c284aa","name":"Letterhead API","type":"collection"}},"urlObject":{"protocol":"https","path":["api","v2","channels","{{channel}}","letters",""],"host":["{{serverPrefix}}","api","tryletterhead","com"],"query":[{"description":{"content":"When true, instructs the endpoint that you're authenticating with an organization key as opposed to some other method. In almost all cases you will want to set this value to true.
List or search through newsletters based on their publication status or keywords.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{apiKey}}"}]},"isInherited":true,"source":{"_postman_id":"b188d139-a966-4327-96e6-e2c968c284aa","id":"b188d139-a966-4327-96e6-e2c968c284aa","name":"Letterhead API","type":"collection"}},"urlObject":{"protocol":"https","path":["api","v2","channels","{{channel}}","letters"],"host":["{{serverPrefix}}","api","tryletterhead","com"],"query":[{"description":{"content":"Publication status of results to include (1 = published; 2 = scheduled; 4 = review; 6 = all statuses)
\n","type":"text/plain"},"key":"filter","value":"6"},{"description":{"content":"Optional keyword by which to search results
\n","type":"text/plain"},"key":"keyword","value":null},{"description":{"content":"Filter results to include only the letter matching the specified UUID.
\n","type":"text/plain"},"key":"letterUuid","value":null},{"description":{"content":"Number of results to return
\n","type":"text/plain"},"key":"limit","value":"10"},{"description":{"content":"Whether to include newsletters marked \"private.\"
\n","type":"text/plain"},"key":"includePrivate","value":"true"},{"description":{"content":"Paginated page number
\n","type":"text/plain"},"key":"page","value":"1"},{"description":{"content":"Whether to authenticate with a passport rather than an API key
\n","type":"text/plain"},"key":"passport","value":"false"},{"description":{"content":"When true, instructs the endpoint that you're authenticating with an organization key as opposed to some other method. In almost all cases you will want to set this value to true.
StartFragment
\nYou can integrate around the newsletters you make to bake it into dashboards or other services you might use. At the moment, our Letters API is read-only.
\nEndFragme
\n","_postman_id":"b186fffc-f7dc-4a74-addf-89f7d33d69e6","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{apiKey}}"}]},"isInherited":true,"source":{"_postman_id":"b188d139-a966-4327-96e6-e2c968c284aa","id":"b188d139-a966-4327-96e6-e2c968c284aa","name":"Letterhead API","type":"collection"}}}],"id":"430fa413-2814-4183-a695-29f5ec4b1c97","description":"The v2 API and the v3 API are almost identical except for scope. The v2 API accommodates organization-wide management, and requires keys generated from the organization level.
required | When set to true, this endpoint will accept authorization with your API Key.
Using the v3 api, which requires a company-level API key, you can list all of your active newsletter templates.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{apiKey}}"}]},"isInherited":true,"source":{"_postman_id":"b188d139-a966-4327-96e6-e2c968c284aa","id":"b188d139-a966-4327-96e6-e2c968c284aa","name":"Letterhead API","type":"collection"}},"urlObject":{"protocol":"https","path":["api","v3","letters","templates","active"],"host":["{{serverPrefix}}","api","tryletterhead","com"],"query":[{"description":{"content":"required | When set to true, this endpoint will accept authorization with your API Key.
required | string[] | An array of channel identifiers (or channel \"slugs\").
This endpoint returns the top 5 and bottom 5 performing subject lines for the authenticated company, ranked by open rate. As a v3 endpoint, it requires a company-derived API key.
It returns two arrays — top and bottom — each containing up to 5 items with the subject line text, open rate percentage, send count, and associated newsletters, channels, and organizations.
No analysis is included; this is purely metrics-driven.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{apiKey}}"}]},"isInherited":true,"source":{"_postman_id":"b188d139-a966-4327-96e6-e2c968c284aa","id":"b188d139-a966-4327-96e6-e2c968c284aa","name":"Letterhead API","type":"collection"}},"urlObject":{"protocol":"https","path":["api","v3","letters","subject-line-performances"],"host":["{{serverPrefix}}","api","tryletterhead","com"],"query":[{"description":{"content":"required | When set to true, this endpoint will accept authorization with your API Key.
required | When set to true, this endpoint will accept authorization with your API Key.
Provided you have any preflight agents, this endpoint allows you to trigger them. The newsletter must be in a preflight status - that is, scheduling - for the agents to actually run.
v3 endpoints expect a company API key.
Provided you have any preflight agents, this endpoint allows you to trigger them. The newsletter must be in a preflight status - that is, scheduling - for the agents to actually run.
v3 endpoints expect a company API key.
required | When set to true, this endpoint will accept authorization with your API Key.
The v3 API is identical to the v2 API in almost every way other than scope. v3 endpoints accommodate company-wide management, and require keys generated from within a company's administrative settings.
This route allows administrators to delete a letter by its unique identifier.
\nWhat is the letter or template's unique identifier? The unique identifier is an alphanumeric string, often around ten digits. It looks like abcdefhijk.
required | Declare the time to schedule the campaign for delivery in ISO 8601 format.
\nExample: 2024-05-29T15:15:00
The time is locale to the Channel's timezone, for now, and must be at least 5 minutes in the future.
\n","type":"text"},{"key":"segment","value":"{{ segmentUuid }}","description":"required | Identify the audience segment you wish to target by passing its identifier. If you pass null, the Letter will send to its entire audience.
optional | Set the subject of your letter. If not present, the letter's subject will be dynamically set based on the first heading found in the content.
\n","type":"text"}]},"url":"https://{{serverPrefix}}.api.tryletterhead.com/api/v2/letters/{{letterUuid}}/actions/schedule","description":"Schedule an existing letter by its unique identifier, or generate and schedule a new letter by using the unique identifier of a template.
\nWhat is the letter or template's unique identifier? The unique identifier is an alphanumeric string, often around ten digits. It looks like abcdefhijk.
How does the API behave when a given letter or template has a specific status?
\nIf the letter is a draft, or it's already been scheduled but not yet published, then Letterhead will reschedule that letter for the desired time.
\nIf the letter has already been published, then Letterhead won't resend it, and the API will return a 400 .
If the template is active, then Letterhead will use that template to create an all-new email, produce it, and schedule it at the desired time.
\nIf the template is inactive, however, then Letterhead will assume your organization doesn't want it used and our API will return a 400.
required | Identify the audience segment you wish to target by passing its identifier. If you pass null, the Letter will send to its entire audience.
optional | Set the subject of your letter. If not present, the letter's subject will be dynamically set based on the first heading found in the content.
\n","type":"text"}]},"url":"https://{{serverPrefix}}.api.tryletterhead.com/api/v2/letters/{{letterUuid}}/actions/send","description":"Send an existing letter immediately by its unique identifier, or generate and send a new letter by using the unique identifier of a template.
\nWhat is the letter or template's unique identifier? The unique identifier is an alphanumeric string, often around ten digits. It looks like abcdefhijk.
How does the API behave when a given letter or template has a specific status?
\nIf the letter is a draft, or it's already been scheduled but not yet published, then Letterhead will reschedule that letter for the desired time.
\nIf the letter has already been published, then Letterhead won't resend it, and the API will return a 400 .
If the template is active, then Letterhead will use that template to create an all-new email, produce it, and schedule it at the desired time.
\nIf the template is inactive, however, then Letterhead will assume your organization doesn't want it used and our API will return a 400.
Schedule an existing letter by its unique identifier, or generate and schedule a new letter by using the unique identifier of a template.
\nWhat is the letter or template's unique identifier? The unique identifier is an alphanumeric string, often around ten digits. It looks like abcdefhijk.
How does the API behave when a given letter or template has a specific status?
\nIf the letter is a draft, or it's already been scheduled but not yet published, then Letterhead will reschedule that letter for the desired time.
\nIf the letter has already been published, then Letterhead won't resend it, and the API will return a 400 .
If the template is active, then Letterhead will use that template to create an all-new email, produce it, and schedule it at the desired time.
\nIf the template is inactive, however, then Letterhead will assume your organization doesn't want it used and our API will return a 400.
The v2 API and the v3 API are almost identical except for scope. The v2 API accommodates organization-wide management, and requires keys generated from the organization level.
Our Letters API -- api/v2/letters/... -- allows developers to interact with an organization's newsletters outside of the constraint of its Channel.
required | array List of email addresses you wish to target.
Note: while \"emails\" implies a plurality, Letterhead presently accepts only one email address.
\n","type":"text","contentType":""},{"key":"html","value":"","description":"required | string The raw, valid HTML body of your email, starting with its opening doctype. Your email must comply with CANSPAM.
required | string The channel identifier (or \"channel slug\") where the recipients of this email are subscribed.
required | string The email subject of the newsletter. Maximum 191 characters.
Send a marketing email with your own HTML.
\nThe emails provided must be current subscribers of the corresponding channel, or Letterhead will return a 400.
Your HTML must comply with all regional laws in addition to CANSPAM.
\nRemember that Gmail will \"clip\" an email that's greater than 102kb. Letterhead won't compress HTML you compose, so be sure to take its filesize in consideration.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{apiKey}}"}]},"isInherited":true,"source":{"_postman_id":"b188d139-a966-4327-96e6-e2c968c284aa","id":"b188d139-a966-4327-96e6-e2c968c284aa","name":"Letterhead API","type":"collection"}},"urlObject":{"protocol":"https","path":["api","v2","marketing","actions","send"],"host":["{{serverPrefix}}","api","tryletterhead","com"],"query":[],"variable":[]}},"response":[{"id":"23a4ba34-fd84-4734-8403-e10c0316e970","name":"Email successfully sent","originalRequest":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[{"key":"emails[]","value":"jdoe@example.com","description":"**required** | `array` List of email addresses you wish to target. \n\n*Note*: while \"emails\" implies a plurality, Letterhead presently accepts only one email address.","type":"text","contentType":""},{"key":"html","value":"We're hoping you have some kind words to say.
","description":"**required** | `string` The raw, valid HTML body of your email, starting with its opening `doctype`. Your email must comply with CANSPAM.","type":"text"},{"key":"channel","value":"black-bitter-coffee-times","description":"**required** | `string` The channel identifier (or \"channel slug\") where the recipients of this email are subscribed.","type":"text"},{"key":"subject","value":"Can we ask you a question?","description":"**required** | `string` The email subject of the newsletter. Maximum 191 characters.","type":"text"}]},"url":"https://{{serverPrefix}}.tryletterhead.com/api/v2/marketing/actions/send"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Server","value":"nginx/1.14.0 (Ubuntu)"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Credentials","value":"true"},{"key":"Access-Control-Max-Age","value":"86400"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Date","value":"Mon, 26 Aug 2024 18:18:33 GMT"}],"cookie":[],"responseTime":null,"body":"\"Your letter with given HTML is scheduled to publish in 5 minutes.\""}],"_postman_id":"ec071fa2-7c45-4b52-be15-9572d30d08d8"}],"id":"08c9081b-035b-4340-bd43-e84b755ce85e","description":"The v2 API and the v3 API are almost identical except for scope. The v2 API accommodates organization-wide management, and requires keys generated from the organization level.
Our Marketing API -- api/v2/marketing/... -- is designed around an organization's marketing need that might exist outside of its regular newsletter strategy.
This API is currently only available on request.
\n","_postman_id":"0d6dec0c-c774-459c-ab28-fc0b8335d415","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{apiKey}}"}]},"isInherited":true,"source":{"_postman_id":"b188d139-a966-4327-96e6-e2c968c284aa","id":"b188d139-a966-4327-96e6-e2c968c284aa","name":"Letterhead API","type":"collection"}}},{"name":"Metrics","item":[{"name":"Get metrics","event":[{"listen":"test","script":{"id":"b0a7b713-f904-4154-bbb3-6547a7f4d99d","exec":["pm.test(\"Status code is 200\", function () {"," pm.response.to.have.status(200);","});",""],"type":"text/javascript","packages":{},"requests":{}}}],"id":"f5ef9e27-09ed-4024-b293-7ad2dedd1f04","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[{"key":"api","value":"true","description":"required | When set to true, this endpoint will accept authorization with your API Key.
required | string | Period start date (inclusive).
required | string | Period end date (inclusive), must be >= from, max 90 days.
string[] | Optionally filter your metrics with a list of channels (by their identifiers).
string | Change sort direction by optionally specifying \"asc\" or \"desc.\" Descending is default.
string | Pass channel to include per-channel breakdown
integer | Items per page for the channel breakdown. Max of 25.
integer | Page number for channel breakdown, as those will be paginated.
string | Sort by \"opens\" or \"channel\" for a channel breakdown. Defaults to \"opens.\"
This action allows organizations to \"confirm\" all subscribers awaiting confirmation of their intent to subscribe (we also call this \"pending optin\") across the entire organization.
\nThe only response is a 200, and it may take several minutes to process.
required | When true, instructs the endpoint that you're authenticating with an organization key as opposed to some other method. In almost all cases you will want to set this value to true.
optional | Starting point of the range following the YYYY-MM-DD format. 30 days ago if not specified
optional | Ending point of the range following the YYYY-MM-DD format. Today if not specified
optional | An array of channel slugs matching. Each channel slug can be input as an array item: channels[0], channels[1], ..., channels[n].
\n","type":"text/plain"},"key":"channels[]","value":"example-channel-slug"},{"description":{"content":"optional | When no channels, displayOrganization has to be 1 (true). 0 for false.
\n","type":"text/plain"},"key":"displayOrganization","value":"1"}],"variable":[]}},"response":[],"_postman_id":"3b86b09e-f121-4d7b-b313-36c39b199ebd"}],"id":"bdd434a8-24cc-43dd-b38e-0f19d433398a","_postman_id":"bdd434a8-24cc-43dd-b38e-0f19d433398a","description":"","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{apiKey}}"}]},"isInherited":true,"source":{"_postman_id":"b188d139-a966-4327-96e6-e2c968c284aa","id":"b188d139-a966-4327-96e6-e2c968c284aa","name":"Letterhead API","type":"collection"}}},{"name":"Channels","item":[{"name":"Metrics","item":[{"name":"Audience","item":[{"name":"Growth metrics","id":"649d7119-ef21-4e27-9482-4f91f0c8066d","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://{{serverPrefix}}.api.tryletterhead.com/api/v2/organizations/my-awesome-organization/channels/{{channel}}/metrics/audience?api=true&from&to","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{apiKey}}"}]},"isInherited":true,"source":{"_postman_id":"b188d139-a966-4327-96e6-e2c968c284aa","id":"b188d139-a966-4327-96e6-e2c968c284aa","name":"Letterhead API","type":"collection"}},"urlObject":{"protocol":"https","path":["api","v2","organizations","my-awesome-organization","channels","{{channel}}","metrics","audience"],"host":["{{serverPrefix}}","api","tryletterhead","com"],"query":[{"description":{"content":"required | When true, instructs the endpoint that you're authenticating with an organization key as opposed to some other method. In almost all cases you will want to set this value to true.
optional | Starting point of the range following the YYYY-MM-DD format. 30 days ago if not specified
optional | Ending point of the range following the YYYY-MM-DD format. Today if not specified
The organization is at the highest level, and all channels belong to an organization. This method allows you to get an array of all channels and their slugs belonging to an organization
When true, instructs the endpoint that you're authenticating with an organization key as opposed to some other method. In almost all cases you will want to set this value to true.
The v2 API and the v3 API are almost identical except for scope. The v2 API accommodates organization-wide management, and requires keys generated from the organization level.