Skip to content

Commit 022fa3b

Browse files
i7ani7an
authored
Merge pull request #53 from sarco3t/batch-sending-api
Batch Sending API
2 parents f42133c + b363fd8 commit 022fa3b

File tree

9 files changed

+632
-6
lines changed

9 files changed

+632
-6
lines changed

‎README.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,38 @@ client.send(
7373

7474
```
7575

76+
### Batch Sending
77+
78+
Send up to 500 emails in one API call:
79+
80+
```ruby
81+
require 'mailtrap'
82+
83+
client = Mailtrap::Client.new(api_key: 'your-api-key')
84+
85+
batch_base = Mailtrap::Mail.batch_base_from_content(
86+
from: { email: 'mailtrap@demomailtrap.co', name: 'Mailtrap Test' },
87+
subject: 'You are awesome!',
88+
text: 'Congrats for sending test email with Mailtrap!',
89+
html: '<p>Congrats for sending test email with Mailtrap!</p>'
90+
)
91+
92+
client.send_batch(
93+
batch_base, [
94+
Mailtrap::Mail.from_content(
95+
to: [
96+
{ email: 'john.doe@email.com', name: 'John Doe' }
97+
]
98+
),
99+
Mailtrap::Mail.from_content(
100+
to: [
101+
{ email: 'jane.doe@email.com', name: 'Jane Doe' }
102+
]
103+
)
104+
]
105+
)
106+
```
107+
76108
### Email Templates API
77109

78110
```ruby
@@ -94,6 +126,7 @@ Refer to the [`examples`](examples) folder for more examples:
94126

95127
- [Full](examples/full.rb)
96128
- [Email template](examples/email_template.rb)
129+
- [Batch Sending](examples/batch.rb)
97130
- [ActionMailer](examples/action_mailer.rb)
98131
- [Email Templates API](examples/email_templates_api.rb)
99132

‎examples/batch.rb‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
require 'mailtrap'
2+
require 'base64'
3+
4+
client = Mailtrap::Client.new(api_key: 'your-api-key')
5+
6+
# Set your API credentials as environment variables
7+
# export MAILTRAP_API_KEY='your-api-key'
8+
#
9+
# client = Mailtrap::Client.new
10+
# Bulk sending (@see https://help.mailtrap.io/article/113-sending-streams)
11+
# client = Mailtrap::Client.new(bulk: true)
12+
# Sandbox sending (@see https://help.mailtrap.io/article/109-getting-started-with-mailtrap-email-testing)
13+
# client = Mailtrap::Client.new(sandbox: true, inbox_id: 12)
14+
15+
# Batch sending with text and html content
16+
batch_base = Mailtrap::Mail.batch_base_from_content(
17+
from: { email: 'mailtrap@demomailtrap.co', name: 'Mailtrap Test' },
18+
subject: 'You are awesome!',
19+
text: 'Congrats for sending test email with Mailtrap!',
20+
html: '<p>Congrats for sending test email with Mailtrap!</p>'
21+
)
22+
23+
File.open('attachment.txt') do |f|
24+
batch_base.add_attachment(content: f, filename: 'attachment.txt')
25+
end
26+
27+
client.send_batch(
28+
batch_base, [
29+
Mailtrap::Mail.from_content(
30+
to: [
31+
{ email: 'john.doe@email.com', name: 'John Doe' }
32+
]
33+
),
34+
Mailtrap::Mail::Base.new(
35+
to: [
36+
{ email: 'jane.doe@email.com', name: 'Jane Doe' }
37+
]
38+
),
39+
{
40+
to: [
41+
{ email: 'david.doe@email.com', name: 'David Doe' }
42+
]
43+
}
44+
]
45+
)
46+
47+
# Batch sending with template
48+
batch_base = Mailtrap::Mail.batch_base_from_template(
49+
from: { email: 'mailtrap@demomailtrap.co', name: 'Mailtrap Test' },
50+
reply_to: { email: 'support@example.com', name: 'Mailtrap Reply-To' },
51+
template_uuid: '339c8ab0-e73c-4269-984e-0d2446aacf2c'
52+
)
53+
54+
client.send_batch(
55+
batch_base, [
56+
Mailtrap::Mail.from_template(
57+
to: [
58+
{ email: 'john.doe@email.com', name: 'John Doe' }
59+
],
60+
template_variables: {
61+
user_name: 'John Doe'
62+
}
63+
),
64+
Mailtrap::Mail::Base.new(
65+
to: [
66+
{ email: 'jane.doe@email.com', name: 'Jane Doe' }
67+
],
68+
template_variables: {
69+
user_name: 'Jane Doe'
70+
}
71+
),
72+
{
73+
to: [
74+
{ email: 'david.doe@email.com', name: 'David Doe' }
75+
],
76+
template_variables: {
77+
user_name: 'David Doe'
78+
}
79+
}
80+
]
81+
)
82+
83+
# You can also pass the request parameters directly
84+
client.send_batch(
85+
{
86+
from: { email: 'mailtrap@demomailtrap.co', name: 'Mailtrap Test' },
87+
reply_to: { email: 'support@example.com', name: 'Mailtrap Reply-To' },
88+
template_uuid: '339c8ab0-e73c-4269-984e-0d2446aacf2c'
89+
}, [
90+
{
91+
to: [
92+
{ email: 'john.doe@email.com', name: 'John Doe' }
93+
],
94+
template_variables: {
95+
user_name: 'John Doe'
96+
}
97+
},
98+
{
99+
to: [
100+
{ email: 'jane.doe@email.com', name: 'Jane Doe' }
101+
],
102+
template_variables: {
103+
user_name: 'Jane Doe'
104+
}
105+
},
106+
{
107+
to: [
108+
{ email: 'david.doe@email.com', name: 'David Doe' }
109+
],
110+
template_variables: {
111+
user_name: 'David Doe'
112+
}
113+
}
114+
]
115+
)

‎lib/mailtrap/client.rb‎

Lines changed: 86 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -37,11 +37,9 @@ def initialize( # rubocop:disable Metrics/ParameterLists
3737
sandbox: false,
3838
inbox_id: nil
3939
)
40-
raise ArgumentError, 'api_key is required' if api_key.nil?
41-
raise ArgumentError, 'api_port is required' if api_port.nil?
40+
validate_args!(api_key, api_port, bulk, sandbox, inbox_id)
4241

4342
api_host ||= select_api_host(bulk:, sandbox:)
44-
raise ArgumentError, 'inbox_id is required for sandbox API' if sandbox && inbox_id.nil?
4543

4644
@api_key = api_key
4745
@api_host = api_host
@@ -53,6 +51,80 @@ def initialize( # rubocop:disable Metrics/ParameterLists
5351
@http_clients = {}
5452
end
5553

54+
# Sends a batch of emails.
55+
# @example Batch sending with template
56+
# batch_base = Mailtrap::Mail.batch_base_from_template(
57+
# from: { email: 'mailtrap@demomailtrap.co', name: 'Mailtrap Test' },
58+
# reply_to: { email: 'support@example.com', name: 'Mailtrap Reply-To' },
59+
# template_uuid: '339c8ab0-e73c-4269-984e-0d2446aacf2c'
60+
# )
61+
#
62+
# client.send_batch(
63+
# batch_base, [
64+
# Mailtrap::Mail.from_template(
65+
# to: [
66+
# { email: 'john.doe@email.com', name: 'John Doe' }
67+
# ],
68+
# template_variables: {
69+
# user_name: 'John Doe'
70+
# }
71+
# ),
72+
# Mailtrap::Mail::Base.new(
73+
# to: [
74+
# { email: 'jane.doe@email.com', name: 'Jane Doe' }
75+
# ],
76+
# template_variables: {
77+
# user_name: 'Jane Doe'
78+
# }
79+
# ),
80+
# {
81+
# to: [
82+
# { email: 'david.doe@email.com', name: 'David Doe' }
83+
# ],
84+
# template_variables: {
85+
# user_name: 'David Doe'
86+
# }
87+
# }
88+
# ]
89+
# )
90+
#
91+
# @example Passing the request parameters directly
92+
# client.send_batch(
93+
# {
94+
# from: { email: 'mailtrap@demomailtrap.co', name: 'Mailtrap Test' },
95+
# reply_to: { email: 'support@example.com', name: 'Mailtrap Reply-To' },
96+
# template_uuid: '339c8ab0-e73c-4269-984e-0d2446aacf2c'
97+
# }, [
98+
# {
99+
# to: [
100+
# { email: 'john.doe@email.com', name: 'John Doe' }
101+
# ],
102+
# template_variables: {
103+
# user_name: 'John Doe'
104+
# }
105+
# },
106+
# {
107+
# to: [
108+
# { email: 'jane.doe@email.com', name: 'Jane Doe' }
109+
# ],
110+
# template_variables: {
111+
# user_name: 'Jane Doe'
112+
# }
113+
# }
114+
# ]
115+
# )
116+
# @param base [#to_json] The base email configuration for the batch.
117+
# @param requests [Array<#to_json>] Array of individual email requests.
118+
# @return [Hash] The JSON response from the API.
119+
# @!macro api_errors
120+
# @raise [Mailtrap::MailSizeError] If the message is too large.
121+
def send_batch(base, requests)
122+
perform_request(:post, api_host, batch_request_path, {
123+
base:,
124+
requests:
125+
})
126+
end
127+
56128
# Sends an email
57129
# @example
58130
# mail = Mailtrap::Mail.from_template(
@@ -124,8 +196,6 @@ def http_client_for(host)
124196
end
125197

126198
def select_api_host(bulk:, sandbox:)
127-
raise ArgumentError, 'bulk mode is not applicable for sandbox API' if bulk && sandbox
128-
129199
if sandbox
130200
SANDBOX_API_HOST
131201
elsif bulk
@@ -139,6 +209,10 @@ def send_path
139209
"/api/send#{"/#{inbox_id}" if sandbox}"
140210
end
141211

212+
def batch_request_path
213+
"/api/batch#{"/#{inbox_id}" if sandbox}"
214+
end
215+
142216
def perform_request(method, host, path, body = nil)
143217
http_client = http_client_for(host)
144218
request = setup_request(method, path, body)
@@ -203,5 +277,12 @@ def response_errors(body)
203277
def json_response(body)
204278
JSON.parse(body, symbolize_names: true)
205279
end
280+
281+
def validate_args!(api_key, api_port, bulk, sandbox, inbox_id)
282+
raise ArgumentError, 'api_key is required' if api_key.nil?
283+
raise ArgumentError, 'api_port is required' if api_port.nil?
284+
raise ArgumentError, 'bulk stream is not applicable for sandbox API' if bulk && sandbox
285+
raise ArgumentError, 'inbox_id is required for sandbox API' if sandbox && inbox_id.nil?
286+
end
206287
end
207288
end

‎lib/mailtrap/mail.rb‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -117,6 +117,75 @@ def from_content( # rubocop:disable Metrics/ParameterLists
117117
)
118118
end
119119

120+
# Builds a base mail object for batch sending using a pre-defined email template.
121+
# This "base" defines shared properties (such as sender, reply-to, template UUID, and template variables)
122+
# that will be used as defaults for all emails in the batch. Individual batch requests can override these values.
123+
# Use this method when you want to send multiple emails with similar content, leveraging a template defined in the Mailtrap dashboard. # rubocop:disable Layout/LineLength
124+
# Template variables can be passed to customize the template content for all recipients, and can be overridden per request. # rubocop:disable Layout/LineLength
125+
# @example
126+
# base_mail = Mailtrap::Mail.batch_base_from_template(
127+
# from: { email: 'mailtrap@example.com', name: 'Mailtrap Test' },
128+
# template_uuid: '2f45b0aa-bbed-432f-95e4-e145e1965ba2',
129+
# template_variables: {
130+
# 'user_name' => 'John Doe'
131+
# }
132+
# )
133+
# # Use base_mail as the base for batch sending with Mailtrap::Client#send_batch
134+
def batch_base_from_template( # rubocop:disable Metrics/ParameterLists
135+
from: nil,
136+
reply_to: nil,
137+
attachments: [],
138+
headers: {},
139+
custom_variables: {},
140+
template_uuid: nil,
141+
template_variables: {}
142+
)
143+
Mailtrap::Mail::Base.new(
144+
from:,
145+
reply_to:,
146+
attachments:,
147+
headers:,
148+
custom_variables:,
149+
template_uuid:,
150+
template_variables:
151+
)
152+
end
153+
154+
# Builds a base mail object for batch sending with custom content (subject, text, html, category).
155+
# This "base" defines shared properties for all emails in the batch, such as sender, subject, and body.
156+
# Individual batch requests can override these values as needed.
157+
# Use this method when you want to send multiple emails with similar custom content to different recipients.
158+
# @example
159+
# base_mail = Mailtrap::Mail.batch_base_from_content(
160+
# from: { email: 'mailtrap@example.com', name: 'Mailtrap Test' },
161+
# subject: 'You are awesome!',
162+
# text: 'Congrats for sending test email with Mailtrap!'
163+
# )
164+
# # Use base_mail as the base for batch sending with Mailtrap::Client#send_batch
165+
def batch_base_from_content( # rubocop:disable Metrics/ParameterLists
166+
from: nil,
167+
reply_to: nil,
168+
attachments: [],
169+
headers: {},
170+
custom_variables: {},
171+
subject: nil,
172+
text: nil,
173+
html: nil,
174+
category: nil
175+
)
176+
Mailtrap::Mail::Base.new(
177+
from:,
178+
reply_to:,
179+
attachments:,
180+
headers:,
181+
custom_variables:,
182+
subject:,
183+
text:,
184+
html:,
185+
category:
186+
)
187+
end
188+
120189
# Builds a mail object from Mail::Message
121190
# @param message [Mail::Message]
122191
# @return [Mailtrap::Mail::Base]

0 commit comments

Comments
 (0)