Java Integation Guide

Welcome to the ReSMS Java integration guide.

This guide explains how you can quickly and securely send SMS messages using the ReSMS API in your Java applications.

Features

Send SMS: Send text messages to phone numbers.
Send OTP: Generate and send one-time passwords (OTP) for user verification.
Verify OTP: Validate OTP codes entered by users.

Installation

First, install our official ReSMS Java SDK:


<dependency>
    <groupId>dev.resms</groupId>
    <artifactId>resms-java-sdk</artifactId>
    <version>1.1.0</version>
</dependency>

Setup

You need to get an API key on ReSMS Dashboard . Then import the package and create a new instance of the ReSMS class with your API key.


import dev.resms.ReSMS;
import dev.resms.core.exception.ReSMSException;
import dev.resms.services.sms.model.SendSmsOptions;
 
public class Main {
    public static void main(String[] args) {
        ReSMS resms = new ReSMS("re_12345"); // Replace with your actual API key
    }
}

Send SMS

Here’s a minimal example to send an SMS:


import dev.resms.ReSMS;
import dev.resms.core.exception.ReSMSException;
import dev.resms.services.sms.model.SendSmsOptions;
 
public class Main {
    public static void main(String[] args) {
        ReSMS resms = new ReSMS("re_12345");
 
        SendSmsOptions smsOptions = SendSmsOptions.builder()
            .to("+33612345678")
            .message("Welcome to ReSMS!")
            .build();
 
        try {
            resms.sms().send(smsOptions);
        } catch (ReSMSException e) {
            System.err.println("Error: " + e.getMessage());
        }
    }
}

Parameters

Possible parameters for sending an SMS:

Field	Type	Required	Description
`to`	String	✅	The phone number of the recipient, in international format (E.164)
`message`	String	✅	The SMS content (160 characters max)
`senderId`	String	❌	The alphanumeric sender name displayed

Here is the parameter type in Java:


public class SendSmsOptions {
    private String to;
    private String message;
    private String senderId;
}

Response

Success Response

The sms.send() method returns a response when the SMS has been successfully sent. The response type is:


public class SendSmsResponse extends Response {
    private SendSmsResponseData data;
 
    public static class SendSmsResponseData {
        private String messageId;
    }
}

Error Response

In case of an error, a ReSMSException is thrown:


public class ReSMSException extends Exception {
    public ReSMSException(String message) {
        super(message);
    }
}

The sms.send() method may return the following errors:

Name	Message
COUNTRY_DETECTION_FAILED	Unable to detect country code from phone number
PHONE_NUMBER_PARSING_FAILED	Invalid phone number
INSUFFICIENT_SMS_QUOTA	Failed to update message status
MESSAGE_STATUS_UPDATE_FAILED	Failed to update message status

Send OTP

Here is a minimal example to send an OTP verification code to a phone number:


import dev.resms.ReSMS;
import dev.resms.services.otp.model.SendOtpOptions;
 
public class Main {
    public static void main(String[] args) {
        ReSMS resms = new ReSMS("re_12345");
 
        SendOtpOptions otpOptions = SendOtpOptions.builder()
            .to("+33612345678")
            .message("Your OTP code is {CODE}")
            .build();
 
        try {
            resms.otp().send(otpOptions);
        } catch (ReSMSException e) {
            System.err.println("Error: " + e.getMessage());
        }
    }
}

Parameters

Possible parameters for sending an OTP:

Field	Type	Required	Description	Default Value
`to`	String	✅	The phone number of the recipient, in international format (E.164)
`message`	String	✅	The SMS content (160 characters max). It must contain `{CODE}`.
`senderId`	String	❌	The alphanumeric sender name displayed
`codeType`	String (`"NUMERIC"`\| `"ALPHA"`)	❌	The type of OTP code to generate	`"NUMERIC"`
`codeLength`	int	❌	The length of the OTP code	6
`validityMinutes`	int	❌	The validity period of the OTP in minutes.	5

Response

Success Response

The otp.send() method returns a response when the OTP has been successfully sent. The response type is:


public class SendOtpResponse extends Response {
    private SendOtpResponseData data;
 
    @Getter
    public static class SendOtpResponseData {
        private String phoneNumber;
        private String expiresAt;
    }
}

Error Response

In case of an error, a ReSMSException is thrown with the error details.

The otp.send() method may return the following errors:

Code	HTTP Status	Message
`INVALID_MESSAGE_TEMPLATE`	400	Message template must contain `{CODE}` placeholder
`INVALID_CODE_LENGTH`	400	Code length must be between 4 and 16
`INVALID_VALIDITY_DURATION`	400	Validity duration must be between 1 minute and 1440 minutes (24 hours)
`TOO_MANY_OTP_REQUESTS`	429	Too many OTP requests for this phone number

Verify OTP

To verify an OTP code entered by the user:


import dev.resms.ReSMS;
import dev.resms.services.otp.model.VerifyOtpOptions;
 
public class Main {
    public static void main(String[] args) {
        ReSMS resms = new ReSMS("re_12345");
 
        VerifyOtpOptions verifyOptions = VerifyOtpOptions.builder()
            .to("+33612345678")
            .code("123456")
            .build();
 
        try {
            VerifyOtpResponse response = resms.otp().verify(verifyOptions);
            System.out.println("OTP verified: " + response.getData().getOtpId());
        } catch (ReSMSException e) {
            System.err.println("Error: " + e.getMessage());
        }
    }
}

Parameters

Possible parameters for verifying an OTP:

Field	Type	Required	Description
`to`	String	✅	The phone number the OTP was sent to, in international format (E.164)
`code`	String	✅	The verification code entered by the user

Here is the parameter type in Java:


public class VerifyOtpOptions {
    private String to;
    private String code;
}

Response

Success Response

The otp.verify() method returns a response indicating whether the OTP is valid or not. The response type is:


@Getter
public class VerifyOtpResponse extends Response {
    private VerifyOtpResponseData data;
 
    @Getter
    public static class VerifyOtpResponseData {
        private String otpId;
        private String phoneNumber;
        private String verifiedAt;
    }
}

Error Response

In case of an error, a ReSMSException is thrown with the error details.

The otp.verify() method may return the following errors:

Code	HTTP Status	Message
`OTP_NOT_FOUND`	404	OTP not found
`OTP_INVALID`	400	OTP is invalid
`OTP_EXPIRED`	400	OTP has expired
`OTP_ALREADY_VERIFIED`	400	OTP already verified
`INVALID_OTP_CODE`	400	Invalid OTP code

Have feedback, found a bug, or want to suggest a feature?

Open an issue on GitHub
Or chat with us directly on Discord — we’re happy to help!