--- title: "Send email messages" method: POST path: "/email/4/messages" tags: ["channels", "email", "email-message-sending"] --- # Send email messages `POST /email/4/messages` ## Request - Base URL: `https://api.infobip.com` (the document declares no server; this is the origin it was published from) - URL: `https://api.infobip.com/email/4/messages` - Auth: one of: - OAuth 2 - Client credentials - Token URL: `https://api.infobip.com/auth/1/oauth2/token` - API key in header `Authorization` - API key in header `Authorization` - HTTP basic 99% of all use cases can be achieved by using this API method. Everything from sending a simple single message to a single destination, up to batch sending of personalized messages to the thousands of recipients with a single API request. Scheduling and every advanced feature you can think of is supported. ## Request body - 34438aa163eb13a2a06ad96ae98170e41cc2ee8902e8b7655aba73ceb0bb23f1EmailRequest - `messages` 34438aa163eb13a2a06ad96ae98170e41cc2ee8902e8b7655aba73ceb0bb23f1EmailMessage[], required: An array of message objects of a single message or multiple messages sent under one bulk ID. - `sender` string: Email address with optional sender name. Note: This field is required if `templateId` is not present. - `destinations` 34438aa163eb13a2a06ad96ae98170e41cc2ee8902e8b7655aba73ceb0bb23f1EmailGroupDestination[], required: An array of destination objects for where messages are being sent. A valid destination is required. Note: Maximum number of recipients is 1000 overall including `to`, `cc` and `bcc` field. - `to` 34438aa163eb13a2a06ad96ae98170e41cc2ee8902e8b7655aba73ceb0bb23f1EmailToDestination[], required: List of TO recipient email addresses. - `destination` string, required: Email address of the recipient in a form of `john.smith@somecompany.com` - `messageId` string: The ID that uniquely identifies the message sent to a recipient. - `placeholders` string: As optional feature, a specific placeholder can be defined whose value will apply only for this destination. Value should be defined as: `{"name": "John"}`. - `cc` 34438aa163eb13a2a06ad96ae98170e41cc2ee8902e8b7655aba73ceb0bb23f1EmailToDestination[]: List of CC recipient email addresses. - `destination` string, required: Email address of the recipient in a form of `john.smith@somecompany.com` - `messageId` string: The ID that uniquely identifies the message sent to a recipient. - `placeholders` string: As optional feature, a specific placeholder can be defined whose value will apply only for this destination. Value should be defined as: `{"name": "John"}`. - `bcc` 34438aa163eb13a2a06ad96ae98170e41cc2ee8902e8b7655aba73ceb0bb23f1EmailToDestination[]: List of BCC recipient email addresses. - `destination` string, required: Email address of the recipient in a form of `john.smith@somecompany.com` - `messageId` string: The ID that uniquely identifies the message sent to a recipient. - `placeholders` string: As optional feature, a specific placeholder can be defined whose value will apply only for this destination. Value should be defined as: `{"name": "John"}`. - `replyTo` string: Email address to which recipients of the email can reply. - `preserveRecipients` boolean: When this option is set to `true`, all recipients in the `to` field will be able to see the entire list of recipients who received the email, and the response will include a single `messageId`. If the option is set to `false` , each recipient will only see their own email address, and the response will provide a unique `messageId` for each individual recipient. - `content` 34438aa163eb13a2a06ad96ae98170e41cc2ee8902e8b7655aba73ceb0bb23f1EmailMessageContent, required: Message content. - `subject` string: Message subject. Note: This field is required if `templateId` is not present. - `text` string: Body of the message. - `html` string: The message's body in HTML format. If both `html` and `text` fields are included, the `text` field will be disregarded, and the message will be sent using the `html` content. - `ampHtml` string: The message's body in AMP HTML format. If you include `ampHtml`, you must also include `html`, which will be displayed if AMP is not supported. Keep in mind that not all email clients support AMP HTML. For guidance on configuring the Gmail client, please visit this link: https://developers.google.com/gmail/ampemail/ . - `templateId` string: The Template ID with predefined email content created through the Infobip web interface or API. When `templateId` is specified, the `html` and `text` fields will be disregarded. Note: `templateId` only supports the `Broadcast` value; `Content` and `Flow` templates are not supported. - `attachments` 34438aa163eb13a2a06ad96ae98170e41cc2ee8902e8b7655aba73ceb0bb23f1EmailMediaAttachment[]: File attachments. - `type` string, required - `inlineImages` 34438aa163eb13a2a06ad96ae98170e41cc2ee8902e8b7655aba73ceb0bb23f1EmailMediaInlineImage[]: Allows for inserting an image file inside the HTML code of the email by using `cid:FILENAME` instead of providing an external link to the image. - `type` string, required - `defaultPlaceholders` string: General placeholders: `{"ph1": "Success"}` will replace the key `{{ph1}}` with the value Success throughout the email, including the `subject`, `text`, and HTML. If there are multiple recipients in the To field, this placeholder will use the same value for the key ph1 for all recipients. - `landingPagePlaceholders` string: Personalize Opt-Out Landing Page by inserting placeholders. Insert placeholder or tag while designing landing page. Value should be defined as: `{"unsubscribe": "Unsubscribe"}` - `optoutLandingPageId` string: The Opt-Out Landing Page ID specifies the page to be displayed when an end user clicks the unsubscribe link. If the ID is not provided, the default opt-out landing page will be used. Create a landing page over Infobip web interface and use its ID, for example, `1_23456.` - `templateLanguageVersion` string: Indicates the version of the template language to be used in the current message template. Use version 1 for the older template language and version 2 to access features of the new template language. If not specified, version 1 will be used by default. - `headers` string: Additional email headers for customization that can be provided in a form of JSON. Example: `headers={"X-CustomHeader": "Header value"}`. There are a few exceptions of headers which are not adjustable through this option: `To`, `Cc`, `Bcc`, `Subject`, `Content-Type`, `DKIM-Signature`, `Content-Transfer-Encoding`, `Return-Path`, `MIME-Version` - `options` 34438aa163eb13a2a06ad96ae98170e41cc2ee8902e8b7655aba73ceb0bb23f1EmailMessageOptions: Message options. - `platform` 34438aa163eb13a2a06ad96ae98170e41cc2ee8902e8b7655aba73ceb0bb23f1Platform: Platform options. For more details, see [documentation](https://www.infobip.com/docs/cpaas-x/application-and-entity-management). - `entityId` string: Used when specifying an entity in outbound send requests. It is also returned in notification events. For detailed usage, refer to the [documentation](https://www.infobip.com/docs/cpaas-x/application-and-entity-management). - `applicationId` string: Used when specifying an application in outbound send requests. It is also returned in notification events. For detailed usage, refer to the [documentation](https://www.infobip.com/docs/cpaas-x/application-and-entity-management). - `validityPeriod` 34438aa163eb13a2a06ad96ae98170e41cc2ee8902e8b7655aba73ceb0bb23f1ValidityPeriod: Message validity period. Once expired, the message won't be sent. Validity period longer than 48h is not supported. If exceeded, it will be automatically set to 48h. - `amount` integer, required: Message validity period's value. If `timeUnit` is not set, it will default to `MINUTES`. - `timeUnit` 'SECONDS' | 'MINUTES' | 'HOURS': Message validity period time unit. - `deliveryTimeWindow` 34438aa163eb13a2a06ad96ae98170e41cc2ee8902e8b7655aba73ceb0bb23f1DeliveryTimeWindow: Sets specific message delivery window outside of which messages won't be delivered. Often, used when there are restrictions on when messages can be sent. The exact time of the day to start sending messages can be defined using the `from` property. The exact time of the day to end sending messages can be defined using the `to` property. Properties `from` and `to` should be both provided with the minimum 1 hour difference or omitted. - `days` 34438aa163eb13a2a06ad96ae98170e41cc2ee8902e8b7655aba73ceb0bb23f1DeliveryDay[], required: Days of the week which are included in the delivery time window. At least one day must be provided. Separate multiple days with a comma. - `from` 34438aa163eb13a2a06ad96ae98170e41cc2ee8902e8b7655aba73ceb0bb23f1DeliveryTime: The exact time of the day. The time is expressed in the UTC time zone. - `hour` integer, required: Hour when the time window opens when used in the `from` property or closes when used in the `to` property. - `minute` integer, required: Minute when the time window opens when used in the `from` property or closes when used in the `to` property. - `to` 34438aa163eb13a2a06ad96ae98170e41cc2ee8902e8b7655aba73ceb0bb23f1DeliveryTime: The exact time of the day. The time is expressed in the UTC time zone. - `hour` integer, required: Hour when the time window opens when used in the `from` property or closes when used in the `to` property. - `minute` integer, required: Minute when the time window opens when used in the `from` property or closes when used in the `to` property. - `campaignReferenceId` string: ID that allows you to track, analyze, and show an aggregated overview and the performance of individual campaigns per sending channel. - `webhooks` 34438aa163eb13a2a06ad96ae98170e41cc2ee8902e8b7655aba73ceb0bb23f1Webhooks: Provides options for configuring message webhooks. - `delivery` 34438aa163eb13a2a06ad96ae98170e41cc2ee8902e8b7655aba73ceb0bb23f1MessageDeliveryReporting: Provides options for configuring the delivery report behavior. - `url` string: The URL on your call back server where a delivery report will be sent. If your URL becomes unavailable then the [retry cycle](https://www.infobip.com/docs/sms/sms-over-api#push-retry-cycle-notify-url) uses the following formula: `1min + (1min * retryNumber * retryNumber)`. - `intermediateReport` boolean: The real-time intermediate delivery report containing GSM error codes, messages status, pricing, network and country codes, etc., which will be sent on your callback server. Defaults to `false`. - `notify` boolean: Notify enables you to specify your preferences for receiving DLRs. If set to false, no DLR will be sent. Note: When no webhook is specified in the request and notify is set to 'true' or not defined, your Subscription settings will apply. - `contentType` string: Preferred delivery report content type, `application/json` or `application/xml`. - `callbackData` string: Additional data that can be used for identifying, managing, or monitoring a message. Data included here will also be automatically included in the message Delivery Report. The maximum value is 4000 characters. - `ips` 34438aa163eb13a2a06ad96ae98170e41cc2ee8902e8b7655aba73ceb0bb23f1EmailIps: IP options per message. - `ipPoolId` string: The ID of the IP pool that will be used to send the email. - `placeholdersMasking` 34438aa163eb13a2a06ad96ae98170e41cc2ee8902e8b7655aba73ceb0bb23f1PlaceholderMasking[]: Options to full or partially mask placeholders. - `name` string, required: The placeholder name that needs to be masked. - `side` string: The side from which characters should be hidden. Options are `L` (left) or `R` (right). - `maskChar` string: The character used to replace the masked placeholders, e.g., `*`, `+`. - `visibleChars` integer: The number of characters to leave visible. Ignored if a delimiter is specified. Defaults to 0 (i.e., all characters hidden) if not specified. - `delimiter` string: Optional delimiter character (e.g., `@`, `/`). When specified, masking applies only to the part of the placeholder before or after the delimiter, depending on the `side` value. If this is set, the `visibleChars` field is ignored. - `skipChars` string[]: A list of characters that should not be masked, even if they fall within the masked region. For example, if we want to mask `(385)-9134849` into `(***)-********`, we should include the characters `(`,`)` and `-` in this list to preserve the formatting. In this case, only digits will be masked while parentheses and dashes remain visible. - `storage` 34438aa163eb13a2a06ad96ae98170e41cc2ee8902e8b7655aba73ceb0bb23f1EmailStorage: [Email storage options](https://www.infobip.com/docs/email/email-storage-and-retrieval) per message. - `skipPassive` boolean: Set to true to skip [passive email storage](https://www.infobip.com/docs/email/email-storage-and-retrieval/passive-email-storage) (long-term storage used for compliance, legal, or audit purposes). If `false` or not set, the account-level setting is used. - `skipActive` boolean: Set to true to skip [active email storage](https://www.infobip.com/docs/email/email-storage-and-retrieval/active-email-storage) (short-term storage used for troubleshooting or support). If `false` or not set, the account-level setting is used. - `options` 34438aa163eb13a2a06ad96ae98170e41cc2ee8902e8b7655aba73ceb0bb23f1EmailMessageRequestOptions: Options applicable to all messages in the request. - `schedule` 34438aa163eb13a2a06ad96ae98170e41cc2ee8902e8b7655aba73ceb0bb23f1EmailRequestSchedulingSettings: Options for scheduling a message. - `bulkId` string: Unique ID assigned to the request if messaging multiple recipients or sending multiple messages via a single API request. If not provided, it will be auto-generated and returned in the API response. - `sendAt` string: Date and time when the message is to be sent. Used for scheduled messages. Has the following format: `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, and can only be scheduled for no later than 5 days in advance. - `tracking` 34438aa163eb13a2a06ad96ae98170e41cc2ee8902e8b7655aba73ceb0bb23f1EmailUrlOptions: Sets up [URL shortening](https://www.infobip.com/docs/url-shortening) and tracking feature. - `track` boolean: Enable or disable open and click tracking. Passing true will only enable tracking and the statistics will be visible in the web interface alone. This can be explicitly overridden by `trackClicks` and `trackOpens`. - `trackOpens` boolean: This parameter enables or disables track open feature. - `trackClicks` boolean: This parameter enables or disables track click feature. - `trackingUrl` string: The URL on your callback server on which the open and click notifications will be sent. See [Tracking Notifications](https://www.infobip.com/docs/email/send-email-over-api#tracking-notifications) for details. - `trackingPixelPosition` string: This parameter specifies the position of the open tracking pixel within the email content. Allowed values are `TOP` and `BOTTOM`. If no value is provided, the default is `TOP`. - `clientPriority` 'HIGH' | 'STANDARD' | 'LOW': Client priority set on request. Must be 'HIGH', 'STANDARD' or 'LOW'. ## Response `200` OK - 34438aa163eb13a2a06ad96ae98170e41cc2ee8902e8b7655aba73ceb0bb23f1EmailResponse - `bulkId` string: Unique ID assigned to the request if messaging multiple recipients or sending multiple messages via a single API request. If not provided, it will be auto-generated and returned in the API response. Typically used for fetching delivery reports and message logs. - `messages` 34438aa163eb13a2a06ad96ae98170e41cc2ee8902e8b7655aba73ceb0bb23f1MessageResponseMessageResponseDetails[], required: An array of message objects of a single message or multiple messages sent under one bulk ID. - `messageId` string: Unique message ID. If not provided, it will be auto-generated and returned in the API response. - `status` 34438aa163eb13a2a06ad96ae98170e41cc2ee8902e8b7655aba73ceb0bb23f1MessageStatus: Indicates the [status](https://www.infobip.com/docs/essentials/response-status-and-error-codes#api-status-codes) of the message and how to recover from an error should there be any. - `groupId` integer: Status group ID. - `groupName` 'ACCEPTED' | 'PENDING' | 'UNDELIVERABLE' | 'DELIVERED' | 'EXPIRED' | 'REJECTED': Status group name that describes which category the status code belongs to, i.e., [PENDING](https://www.infobip.com/docs/essentials/response-status-and-error-codes#pending-general-status-codes), [UNDELIVERABLE](https://www.infobip.com/docs/essentials/response-status-and-error-codes#undeliverable-general-status-codes), [DELIVERED](https://www.infobip.com/docs/essentials/response-status-and-error-codes#delivered-general-status-codes), [EXPIRED](https://www.infobip.com/docs/essentials/response-status-and-error-codes#expired-general-status-codes), [REJECTED](https://www.infobip.com/docs/essentials/response-status-and-error-codes#rejected-general-status-codes). - `id` integer: Status code ID. - `name` string: [Status code](https://www.infobip.com/docs/essentials/response-status-and-error-codes#api-status-codes) name. - `description` string: Human-readable description of the status. - `action` string: Action to take to recover from the error. - `destination` string: The destination address of the message, i.e., its recipient. - `details` 34438aa163eb13a2a06ad96ae98170e41cc2ee8902e8b7655aba73ceb0bb23f1MessageResponseDetails: Other details of the message. ## Other responses - `400`: Bad Request - `401`: Unauthorized - `403`: Forbidden - `429`: Too Many Requests - `500`: Internal Server Error --- [API](https://skmtc.dev/infobip/apis/infobip-openapi-specification.md) - [All operations](https://skmtc.dev/infobip/apis/infobip-openapi-specification/llms.txt) - [OpenAPI document](https://skmtc.dev/infobip/apis/infobip-openapi-specification/revisions/9dcbbaf902de?raw)