--- title: "Add a translation to a one-time send" method: POST path: "/v1/newsletters/{newsletter_id}/language" tags: ["Newsletter Variants"] --- # Add a translation to a one-time send `POST /v1/newsletters/{newsletter_id}/language` ## Request - Base URL: `https://api.customer.io` - URL: `https://api.customer.io/v1/newsletters/{newsletter_id}/language` - Auth: HTTP bearer Add a language variant to a one-time send (referred to as a "newsletter" in our APIs). If you omit optional fields, the values from the default template are copied over untranslated. Make sure you translate all aspects of your default template. You can't add language variants to a one-time send that has already been sent. You can't manage emails created with the drag-and-drop editor or Design Studio via this endpoint—use [Create an email translation](/integrations/api/design-studio/tag/emails/createEmailTranslation/) for Design Studio emails. If it has A/B tests, use [Add a translation to a one-time send test group](/integrations/api/app/tag/newsletter-variants/createNewsletterTestLanguageVariant/) instead. ## Request body - union: Add a language variant to a one-time send. The payload the endpoint accepts depends on the parent one-time send's channel type. - object: Add a language variant to an email one-time send. Requires `language`, `subject`, and `body`. - `language` string, required: The [language tag](/journeys/channels/localization/attribute/#supported-languages) for the new variant, e.g. `es`, `fr`, `de`. - `subject` string, required: The subject line for the variant. - `preheader_text` string: The preheader text for the email variant. - `body` string, required: The HTML body content for the variant. - `body_plain` string: The plaintext body content for the variant. - `body_amp` string: The AMP HTML body content for the variant. - object: Add a language variant to an SMS one-time send. Requires `language` and `body`. - `language` string, required: The [language tag](/journeys/channels/localization/attribute/#supported-languages) for the new variant, e.g. `es`, `fr`, `de`. - `body` string, required: The body content of the SMS message. - object: Add a language variant to a push notification one-time send. Requires `language` and at least one of `subject` or `body`. - `language` string, required: The [language tag](/journeys/channels/localization/attribute/#supported-languages) for the new variant, e.g. `es`, `fr`, `de`. - `subject` string: The title of the push notification. - `body` string: The body content of the push notification. - object: Add a language variant to a webhook one-time send. Requires `language` and `body`. - `language` string, required: The [language tag](/journeys/channels/localization/attribute/#supported-languages) for the new variant, e.g. `es`, `fr`, `de`. - `body` string, required: The body content of the webhook request. - object: Add a language variant to an inbox message one-time send. Requires `language` and `body_json`. - `language` string, required: The [language tag](/journeys/channels/localization/attribute/#supported-languages) for the new variant, e.g. `es`, `fr`, `de`. - `body_json` string, required: JSON body content for the inbox message variant. Learn more about [message settings](/journeys/channels/in-app/inbox/send-inbox/) in our docs. ## Response `200` Returns the updated one-time send, including new `content_ids`. - object - `newsletter` NewsletterObject - `id` integer: The identifier for a one-time send. - `deduplicate_id` string: An identifier in the format `id:timestamp` where the id is for the object you're working with (Automations, Deliveries, Exports, Identities, One-time sends, Segments, and Templates), and the timestamp is the last time the object was updated. - `content_ids` integer[]: A list of message variants in a one-time send, where a variant is a translation or A/B test. - `name` string: The name of the one-time send. Must be 190 characters or less. - `sent_at` integer, nullable: The last time the one-time send was sent, or `null` if it hasn't been sent. - `send_state` 'drafted' | 'scheduled' | 'sending' | 'sent' | 'paused' | 'stopped' | 'failed' | 'awaiting_winner': Where the one-time send is in its lifecycle. Always included. This matches the status shown in Customer.io, with one exception noted under `awaiting_winner`. - `drafted`: The one-time send isn't scheduled and hasn't been sent. - `scheduled`: A send time is set and sending hasn't started. - `sending`: Sending has started and is still in progress. More batches are due (timezone-match batches or the remainder of an A/B test), or messages are still being delivered. - `sent`: The one-time send is no longer sending. This doesn't mean that every individual message has reached a final state. - `paused`: The one-time send is paused. - `stopped`: The one-time send was stopped. - `failed`: The one-time send failed. - `awaiting_winner`: An A/B test has started and is waiting for you to pick a winner before the rest of the audience gets it. Test messages might still be going out. Customer.io's UI stops showing "awaiting winner" 30 days after the first send, but the API keeps reporting `awaiting_winner` because you can still pick a winner. When more than one state applies, Customer.io reports the first match in this order: `stopped`, `failed`, `paused`, `awaiting_winner`, `sending`, `sent`, `scheduled`, `drafted`. - `scheduled_at` integer, nullable: When the one-time send is scheduled to go out, or `null` if it has no active schedule. Always included. - A paused one-time send keeps its schedule, so this still has a value while `send_state` is `paused`. - After sending starts, this stores the next scheduled send if there is one, like the next timezone batch or the remainder of an A/B test. - When `tz_match_enabled` is `true`, the `scheduled_at` property is the time you asked for in the [schedule request](/integrations/api/app/tag/send-messages/scheduleNewsletter/) until sending starts. - If you send immediately instead of scheduling, there's a short delay before Customer.io starts sending. During that delay, `scheduled_at` isn't `null` and isn't a future time: it's the time you made the request, an earlier time, or `0`. - `timezone` string: The [IANA timezone name](/journeys/send/timezones/example-timezones/#region-format) of the schedule (for example, `America/New_York`). Customer.io includes this field only when the active schedule has a timezone. It's omitted otherwise. - `tz_match_enabled` boolean: `true` when the pending schedule sends at the same local time in each person's timezone. Customer.io includes this field only while a timezone-match schedule is pending. It's omitted otherwise and is never `false`. - `created` integer: The date time when the referenced ID was created. - `updated` integer: The date time when the referenced ID was last updated. - `type` 'email' | 'webhook' | 'twilio' | 'push' | 'in_app' | 'inbox': Channel type for a one-time send or one-time send content variant. - `tags` string[]: An array of tags associated with the one-time send. - `recipient_segment_ids` integer[]: If the recipient conditions included segments, this returns a list of those segment ids. - `subscription_topic_id` integer: If you enabled a [subscription center](/journeys/channels/subscriptions/center/) on your workspace, this returns the id of the subscription preference you set. - `expires_after` integer: The send window in seconds, if you set one. Customer.io stops delivering the one-time send this long after it starts. - `recipient_file_status` 'pending' | 'processing' | 'done' | 'error': How far Customer.io has got with a recipient file, whether you uploaded it in the UI or passed `recipient_file_url`. Customer.io omits this field when the audience came from a `recipients` filter. Wait for `done` before you send or schedule. - `recipient_file_error` string: Why the recipient file failed, when `recipient_file_status` is `error`. Customer.io omits it otherwise. ## Other responses - `400`: The request is invalid. Possible reasons include: the one-time send has already been sent, the one-time send has multiple test groups ([add a translation to a test group](/integrations/api/app/tag/newsletter-variants/createNewsletterTestLanguageVariant/) instead), or the one-time send uses Design Studio or drag-and-drop editors. - `404`: The one-time send does not exist. - `422`: Validation error. Possible reasons: `language` is missing, required content fields are missing for the channel type, or the language variant already exists. - `429`: Your request is over the 10-per-second limit. `Retry-After` tells you how many seconds you must wait before you send the next request. ## Changes - **2026-10-03** `f3a28f896929`: 1 breaking, 4 info - the response property `newsletter/sent_at` became nullable for the status `200` - added the optional property `newsletter/scheduled_at` to the response with the `200` status - added the optional property `newsletter/send_state` to the response with the `200` status - added the optional property `newsletter/timezone` to the response with the `200` status - …1 more - **2026-09-21** `7aca33a41082`: 3 info - added the optional property `newsletter/expires_after` to the response with the `200` status - added the optional property `newsletter/recipient_file_error` to the response with the `200` status - added the optional property `newsletter/recipient_file_status` to the response with the `200` status - **2026-09-02** `5da2740beeb5`: 1 info - added the media type `application/json` for the response with the status `429` [Operation history](https://skmtc.dev/customer/apis/customer-io-journeys-api-reference/changes/v1/newsletters/:newsletter_id/language/post.md) --- [API](https://skmtc.dev/customer/apis/customer-io-journeys-api-reference.md) - [All operations](https://skmtc.dev/customer/apis/customer-io-journeys-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/customer/apis/customer-io-journeys-api-reference/revisions/ac0b282053fe?raw)