Lockally

      Use your API key in the examples

      Replaces lk_live_… in the code samples on this site so you can copy and run them. It is stored in this browser only and is never sent anywhere, including to Ask AI.

      It will be visible on the page. Use a test key if you are sharing your screen or taking screenshots.

      Sending with an SDK

      Sending is one method on SendApi. The fields are exactly those of POST /v1/send, so that page remains the reference for what each one means; this page is about the parts the client shapes.

      The idempotency key is a separate argument

      await api.sendEmail({
        idempotencyKey: 'welcome-user-42',
        sendEmailRequest: { from, to, subject, text },
      });

      It is not a field inside the body. Every client takes it as its own parameter, because it is an HTTP header, and it is required: a send without one is rejected with 400.

      Choose a key derived from what you are sending, not a random one. A random key per attempt defeats the purpose, because a retry then looks like a new send. order-4021-receipt is a good key; a UUID generated at call time is not. See Idempotency.

      Sending from a template

      The same method, with templateId and variables instead of a body:

      await api.sendEmail({
        idempotencyKey: 'receipt-4021',
        sendEmailRequest: {
          from: 'receipts@yourcompany.com',
          to: ['customer@example.com'],
          templateId: '8c1d4f2a-6b3e-4d19-9a27-5e0f1c8b7a44',
          variables: { name: 'Alice', order_id: '4021' },
        },
      });

      Mutually exclusive with inline content. Passing templateId alongside subject, text or html is a 400, and the typed models will not stop you, because the spec expresses the rule in prose rather than in the schema.

      A missing variable renders as an empty string rather than erroring, so a misspelled key produces a blank in the message and a 202. See Templates.

      Reading the response

      const data = await api.sendEmail({ ... });
      data.id;          // the Lockally id. Store this one
      data.messageId;   // the Internet Message-ID
      data.status;      // queued | scheduled | delivered | suppressed

      Note also that status carries information the HTTP code does not: a test-key send and a real send are both 202, and only the body distinguishes them.

      Field naming across languages

      The generator adapts field names to each language’s conventions, so the wire field template_id is templateId in TypeScript, template_id in Python and Ruby, and TemplateId in C#.

      The one that bites is from, a reserved word in several languages. Python renames it to var_from. Check your client’s generated model rather than assuming the wire name.

      Batch sending

      sendBatch takes up to 500 independent messages and returns a result per message. It returns 200 even when every message failed, so you must iterate the results and check each entry rather than trusting the status code. See Batch sending.

      Attachments

      Attachments are base64 strings in the request body, so the client does no file handling for you: read the file, encode it, set contentType yourself. Nothing is inferred from the filename. See Attachments.