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.