This API call is a generic outbound email sending interface that is designed to enable efficient large-scale email sending through your account’s email servers. It is ideal for Secure High Volume email sending.
See - [sendEmail vs sendSecureEmailOrSecureText endpoints](/rest-api/sending-email.html) for sending email via the LuxSci API.
This API function is used to send message(s) through your account’s SMTP server(s). You can think of it as an API-based proxy to SMTP, used for cases where direct use of SMTP is not an option. Generally speaking, direct use of SMTP is overall faster and more efficient; however, the API does include some things that you cannot get through direct SMTP connections. For example, the API includes support for failover, load-balanced SMTP servers; this can be done with direct SMTP only if you have a load balancer in front of your servers. You can also hand off messages to LuxSci (into the outbound queues) faster through the API than you can through direct SMTP.
As this is a proxy for SMTP, the majority of the email message processing actually happens on the SMTP servers themselves (just like it would if you had actually used direct SMTP to send the message). The API call accepts the message, vets your ability to send the message, queues the message, and the moves it to the appropriate SMTP servers for delivery. This API process is designed to be very safe and efficient and works well for customers with very large SMTP sending limits (e.g., millions of messages per month).
This API function allows you to optionally include attachments. If you wish to include attachments, you must format your request as a `multipart/form-data` request as discussed in the [API Mechanics Guide](/rest-api/mechanics.html).
If the API call 'fails' it may be because more information is needed to encrypt the message to your recipients, if the request is malformed, or if your sending has exceeded some limit. Here are some limits to be aware of
1. The sending user must have an SMTP license.
2. The sending user must have a SecureLine license to use SecureLine-specific parameters.
3. You have to send to at least 1 recipient, but no more than 100 recipients per message. This limit can be increased on dedicated servers.
4. Your API call can contain 1 to 1000 messages. This limit can be increased on dedicated servers.
5. The total number of recipients across all messages in your API call cannot exceed 1000. This limit can be increased on dedicated servers.
6. The messages sent by a user through this API call count towards the users’ daily and monthly SMTP sending (just as if the user had actually used direct SMTP to send) totals. So, messages will be rejected if a user exceeds any of these limits. Please contact support if you need to upgrade these limits.
7. While SecureLine-encrypted emails sending is supported through this API call, SecureText sending is not.
8. If there are restrictions configured in the Domain Administration control panel on to whom the sending user can send messages, these restrictions also apply to messages sent through the API.
9. The total size of the message subject, body, and all attachments (raw size) must be less than or equal to 66% the sender’s SMTP message sending size limit. This limit can be affected by use of Email Archival, custom domain-level size limits, and general global limits. The current value of this limit can be found in the “Maximum Message Size Limit” for the sender’s domain in your domain administration settings area. 66% is used because, when the attachments are encoded into an actual email message, the size can bloat to 140-150% of the raw size; the SMTP message size limit looks at the size of the encoded messages passing through your SMTP servers.
Note that once messages sent via this API arrive on your SMTP server for processing and delivery, those messages are subject to any server delivery rate limiting settings currently enabled on the SMTP server. For example, if your SMTP server is “warming up” its IP address by slowly increasing its outbound email delivery rate, messages sent by the API through that server may be delayed by that warmup rate limit.
**Maximizing your sending rate:**
To deposit email messages in the outbound queues as fast as possible using the API, we recommend
1. Send as many messages as you can in each API call. This “pipelining” greatly reduces the number of API calls you need to execute and greatly speeds up processing of your messages.
2. When sending same attachments in multiple messages, use the API’s feature for including the attachment once and referencing it in each of the actual messages. This will greatly speed up the uploading/posting of your message information to the API server.
3. Keep the messages as small as possible.
4. If appropriate for your use case, send fewer messages. Have more recipients per message (using the `bcc` field if needed).
5. Ask support about dedicated API servers. If all of the server resources are dedicated to your account, your throughput can be higher. You can also use multiple load-balanced dedicated API sending servers to scale your throughput capacity.
6. Use the `priority` field to ensure that more important messages are processed and delivered before less important messages.
Under ideal conditions, you should be able to deposit outbound email messages in the API queues much faster that your email servers can actually deliver those messages to the actual recipients (unless you have a number of powerful dedicated email servers). That is OK, your email servers will just process and delivery them as fast as they can. The actual rate of message delivery to the recipients will be a function of how many email servers you have, what their specs are, how busy they are, and many other factors involved in SMTP email delivery – such as the recipients’ DNS response time, the recipient’s inbound email server speeds, etc.
Access control required to execute this endpoint: User Email: Sending
/perl/api/v2/user/{username}/email/send
Parameters
Path parameters
| Name |
Description |
| username* |
|
Header parameters
Body parameters
Form parameters
| Name |
Description |
| json |
userusernameemailsend_json
|
| files |
|
Responses
Status: 200 - The response body for a successful request will contain a hash in the “data” field. The value of this data field is an array which lists the unique sendmail_id codes for each of the messages sent. These codes can be used in the reporting API functions to look up delivery status and other message details. If multiple messages were sent in a single API call, multiple sendmail_id codes will be returned and the order of the codes in the array will exactly match the order of the messages in the API call.
